textmode.js 0.7.1 → 0.8.0-beta.2

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

@@ -1,22 +1,22 @@
 import type { TextmodeGrid } from '../Grid';
 import type { TextmodeFont } from '../loadables/font';
 import type { TextmodeImage } from '../loadables/TextmodeImage';
-import type { TextmodeSource } from '../loadables/TextmodeSource';
 import type { TextmodeCanvas } from '../Canvas';
 import type { AnimationController } from '../AnimationController';
-import type { GLFramebuffer, GLShader } from '../../rendering';
+import type { GLShader } 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';
 import type { TextmodeLayerManager } from '../layers';
+import type { BuiltInFilterName, BuiltInFilterParams, TextmodeFilterManager, FilterName } from '../filters';
+import type { TextmodeConversionManager } from '../conversion';
 /**
  * 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.
@@ -25,15 +25,11 @@ import type { TextmodeLayerManager } from '../layers';
  * 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 {
+export interface ITextmodifier extends IRenderingMixin, 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 */
@@ -42,24 +38,72 @@ export interface ITextmodifier extends IRenderingMixin, IFontMixin, IAnimationMi
     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: GLShader;
-    /** Framebuffer used for textmode conversion @ignore */
-    readonly _textmodeFramebuffer: GLFramebuffer;
     /** Shader used for final presentation to the screen @ignore */
     readonly _presentShader: GLShader;
     /** Loading screen manager for boot-time UX @ignore */
     readonly _loading: LoadingScreenManager;
-    /** Sources registered for rendering @ignore */
-    readonly _sources: Set<TextmodeSource>;
+    /** Conversion manager for image-to-ASCII conversion @ignore */
+    readonly _conversionManager: TextmodeConversionManager;
+    /** Filter manager for applying post-processing effects @ignore */
+    readonly _filterManager: TextmodeFilterManager;
     /** Layer manager for handling multiple layers @ignore */
     readonly _layerManager: TextmodeLayerManager;
-    /** @ignore */
-    $registerSource(source: TextmodeSource): void;
+    /** Active font based on layer, or loading screen font override @ignore */
+    _activeFont?: TextmodeFont;
+    /** Active grid based on layer currently being rendered @ignore */
+    _activeGrid?: TextmodeGrid;
     /** Main render method @ignore */
     $render(): void;
+    /**
+     * Load a font for the base layer and return it.
+     *
+     * The returned font can be reused on other layers via {@link TextmodeLayer.loadFont}.
+     *
+     * @param fontSource The URL of the font to load.
+     * @returns The loaded TextmodeFont instance (base layer font).
+     *
+     * @example
+     * ```javascript
+     * const t = textmode.create();
+     *
+     * t.setup(async () => {
+     *   // Load font for the base layer
+     *   const font = await t.loadFont('./fonts/myfont.ttf');
+     *
+     *   // Use the same font on another layer
+     *   const layer = t.layers.add();
+     *   await layer.loadFont(font);
+     *
+     *   // Or load a different font for a layer
+     *   await layer.loadFont('./fonts/otherfont.ttf');
+     * });
+     * ```
+     */
+    loadFont(fontSource: string): Promise<TextmodeFont>;
+    /**
+     * Set the font size used for rendering.
+     * @param size The font size to set.
+     *
+     * @example
+     * ```javascript
+     * // Create a Textmodifier instance
+     * const t = textmode.create();
+     *
+     * t.setup(() => {
+     *  // Set the font size to 32
+     *  t.fontSize(32);
+     * });
+     *
+     * t.draw(() => {
+     *  t.background(0);
+     *  t.char('A');
+     *  t.rect(5, 5);
+     * });
+     * ```
+     */
+    fontSize(size: number): void;
     /**
      * Set a setup callback function that will be executed once when initialization is complete.
      *
@@ -207,9 +251,40 @@ export interface ITextmodifier extends IRenderingMixin, IFontMixin, IAnimationMi
      * ```
      */
     destroy(): void;
-    /** Get the current grid object used for rendering. */
-    readonly grid: TextmodeGrid;
-    /** Get the current font object used for rendering. */
+    /**
+     * Apply a filter to the final composited output.
+     *
+     * Filters are applied after all layers are composited but before
+     * the result is presented to the canvas. Multiple filters can be
+     * queued per frame and will be applied in order.
+     *
+     * @param name The name of the filter to apply (built-in or custom)
+     * @param params Optional parameters for the filter
+     *
+     * @example
+     * ```typescript
+     * t.draw(() => {
+     *     t.background(0);
+     *     t.charColor(255);
+     *     t.char('A');
+     *     t.rect(10, 10);
+     *
+     *     // Apply built-in filters
+     *     t.filter('grayscale', 0.5);
+     *     t.filter('invert');
+     *
+     *     // Chain multiple filters
+     *     t.filter('sepia', { amount: 0.3 });
+     *     t.filter('threshold', 0.5);
+     * });
+     * ```
+     */
+    filter<T extends BuiltInFilterName>(name: T, params?: BuiltInFilterParams[T]): void;
+    filter(name: FilterName, params?: unknown): void;
+    filter(name: FilterName, params?: unknown): void;
+    /** Get the grid object used for rendering the base layer. */
+    readonly grid: TextmodeGrid | undefined;
+    /** Get the current font object used for rendering the base layer. */
     readonly font: TextmodeFont;
     /** Get the width of the canvas in pixels. */
     readonly width: number;
@@ -217,10 +292,50 @@ export interface ITextmodifier extends IRenderingMixin, IFontMixin, IAnimationMi
     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;
+    /**
+     * Access the filter manager for this Textmodifier instance.
+     *
+     * Use this to register custom filters that can be applied both globally
+     * (via {@link filter}) and on individual layers (via {@link TextmodeLayer.filter}).
+     * Filters only need to be registered once and are available everywhere.
+     *
+     * @example
+     * ```typescript
+     * // Register a custom filter once
+     * await t.filters.register('vignette', vignetteShader, {
+     *     u_intensity: ['intensity', 0.5]
+     * });
+     *
+     * t.draw(() => {
+     *     t.background(0);
+     *     t.char('A');
+     *     t.rect(10, 10);
+     *
+     *     // Apply filter globally to final output
+     *     t.filter('vignette', { intensity: 0.8 });
+     *
+     *     // Or apply to a specific layer
+     *     t.layers.base.filter('vignette', 0.5);
+     * });
+     * ```
+     */
+    readonly filters: TextmodeFilterManager;
+    /**
+     * Access the layer manager for this Textmodifier instance.
+     *
+     * Use this to create and manage multiple layers within the textmode rendering context.
+     * Each layer can have its own grid, font, draw callback, and filters.
+     */
+    readonly layers: TextmodeLayerManager;
+    /**
+     * Access the conversion manager for this Textmodifier instance.
+     *
+     * Use this to register custom conversion strategies that can be used
+     * when converting images/videos/canvases into textmode representations.
+     */
+    readonly conversions: TextmodeConversionManager;
     /**
      * If in overlay mode, returns the {@link TextmodeImage} instance capturing the target canvas/video content,
      * allowing further configuration of the conversion parameters.
@@ -252,35 +367,35 @@ export interface ITextmodifier extends IRenderingMixin, IFontMixin, IAnimationMi
      * 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!');
-    * });
-    * ```
+     * ```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/layers/Layer2DCompositor.d.ts

@@ -4,28 +4,26 @@ import type { TextmodeLayer } from './TextmodeLayer';
  * Parameters for the composite operation.
  */
 export interface CompositeParams {
-    /** The base texture to composite onto. */
-    baseTexture: WebGLTexture;
+    /** The base layer placement (texture + size + offset). */
+    base: CompositeLayerPlacement;
+    /** The array of user layer placements to composite on top of the base. */
+    layers: readonly CompositeLayerPlacement[];
     /** The target framebuffer to render the final result into. */
     targetFramebuffer: GLFramebuffer;
     /** The background color as RGBA values (0-1 range). */
     backgroundColor: [number, number, number, number];
-    /** The base layer configuration (visibility, opacity, offset). */
-    baseLayer: TextmodeLayer;
-    /** The array of user layers to composite on top of the base. */
-    layers: readonly TextmodeLayer[];
     /** Canvas width in pixels. */
     canvasWidth: number;
     /** Canvas height in pixels. */
     canvasHeight: number;
-    /** Grid width in pixels (layer size). */
-    gridWidth: number;
-    /** Grid height in pixels (layer size). */
-    gridHeight: number;
-    /** X offset to center the grid within the canvas. */
-    baseOffsetX: number;
-    /** Y offset to center the grid within the canvas. */
-    baseOffsetY: number;
+}
+export interface CompositeLayerPlacement {
+    layer: TextmodeLayer;
+    texture: WebGLTexture;
+    width: number;
+    height: number;
+    offsetX: number;
+    offsetY: number;
 }
 /**
  * Handles the compositing of multiple layers using shader-based blending.
@@ -49,15 +47,10 @@ export declare class Layer2DCompositor {
     /**
      * Create a new LayerCompositor.
      * @param renderer The WebGL renderer instance.
-     */
-    constructor(renderer: GLRenderer);
-    /**
-     * Initialize the compositor's framebuffers.
      * @param canvasWidth The canvas width in pixels.
      * @param canvasHeight The canvas height in pixels.
-     * @ignore
      */
-    $initialize(canvasWidth: number, canvasHeight: number): void;
+    constructor(renderer: GLRenderer, canvasWidth: number, canvasHeight: number);
     /**
      * Composite all layers onto the target framebuffer.
      * @param params The composite parameters.

package/dist/types/textmode/layers/LayerManager.d.ts

@@ -3,9 +3,11 @@ import type { Textmodifier } from '../Textmodifier';
 import { TextmodeLayer } from './TextmodeLayer';
 import type { TextmodeLayerOptions } from './types';
 import type { ILayerManager } from './interfaces/ILayerManager';
+import type { TextmodeOptions } from '../types';
+import type { TextmodeGrid } from '../Grid';
 /**
- * Manages all user-defined layers within a Textmodifier instance.
- *
+ * Manages all user-defined layers within a Textmodifier in *
+ * Th *
  * This manager is responsible for:
  * - Managing the collection of user layers (add, remove, move, swap)
  * - Coordinating layer rendering and compositing
@@ -19,36 +21,34 @@ export declare class LayerManager implements ILayerManager {
     private readonly _renderer;
     private readonly _conversionShader;
     private readonly _compositor2D;
-    private readonly _pendingLayers;
-    private readonly _layers;
+    private _pendingLayers;
+    private _layers;
     private readonly _baseLayer;
-    private _baseFramebuffer;
-    private _baseRawFramebuffer;
-    private _layerPingPongBuffers;
     private _isReady;
+    private readonly _gridDimensionChangeCallbacks;
     /**
      * Create a new LayerManager.
      * @param textmodifier The Textmodifier instance this manager belongs to.
      * @ignore
      */
-    constructor(textmodifier: Textmodifier);
+    constructor(textmodifier: Textmodifier, opts: TextmodeOptions);
+    /**
+     * Initialize all pending layers and the compositor.
+     * @ignore
+     */
+    $initialize(): Promise<void>;
     add(options?: TextmodeLayerOptions): TextmodeLayer;
     remove(layer: TextmodeLayer): void;
     move(layer: TextmodeLayer, newIndex: number): void;
     swap(layerA: TextmodeLayer, layerB: TextmodeLayer): void;
     clear(): void;
-    /**
-     * Initialize all pending layers and the compositor.
-     * @ignore
-     */
-    $initialize(): void;
     /**
      * Render all layers (base and user) and composite them to the target framebuffer.
      * @param targetFramebuffer The framebuffer to render the final composited result to.
      * @param backgroundColor The background color as RGBA values (0-1 range).
      * @ignore
      */
-    $renderAndComposite(targetFramebuffer: GLFramebuffer, backgroundColor: [number, number, number, number]): void;
+    $renderAndComposite(targetFramebuffer: GLFramebuffer, fallbackBaseDraw: () => void): void;
     /**
      * Render all user layers to their respective framebuffers.
      */
@@ -70,15 +70,26 @@ export declare class LayerManager implements ILayerManager {
     get all(): readonly TextmodeLayer[];
     get base(): TextmodeLayer;
     /**
-     * Initialize a single layer with required dependencies.
+     * Get the grid of the topmost visible layer.
+     * Returns the topmost user layer's grid if any are visible, otherwise returns the base layer's grid.
+     * This is useful for input managers that need to map coordinates to the layer the user sees on top.
      */
-    private _initializeLayer;
+    getTopmostGrid(): TextmodeGrid | undefined;
+    /**
+     * Register a callback to be invoked whenever ANY layer's grid dimensions change.
+     * This includes the base layer and all user layers.
+     * @param callback The callback to invoke on dimension changes.
+     * @ignore
+     */
+    $onAnyGridDimensionChange(callback: () => void): void;
     /**
-     * Initialize the base layer with external (shared) framebuffers.
-     * The base layer shares the main textmode draw framebuffer and uses
-     * the manager's base framebuffer for ASCII output.
+     * Notify all registered callbacks that a grid's dimensions have changed.
      */
-    private _initializeBaseLayer;
+    private _notifyGridDimensionChange;
+    /**
+     * Initialize a single layer with required dependencies.
+     */
+    private _initializeLayer;
     /**
      * Remove a layer from a collection and dispose it.
      */

package/dist/types/textmode/layers/TextmodeLayer.d.ts

@@ -1,8 +1,9 @@
-import type { GLFramebuffer, GLShader } from '../../rendering';
-import type { TextmodeGrid } from '../Grid';
-import type { Textmodifier } from '../Textmodifier';
+import type { GLFramebuffer, GLRenderer, GLShader } from '../../rendering';
+import { TextmodeGrid } from '../Grid';
+import { TextmodeFont } from '../loadables/font';
+import { Textmodifier } from '../Textmodifier';
 import type { TextmodeLayerBlendMode, TextmodeLayerOptions, LayerDependencies } from './types';
-import type { FilterName, BuiltInFilterName, BuiltInFilterParams, QueuedFilter } from '../filters';
+import type { FilterName, BuiltInFilterName, BuiltInFilterParams } from '../filters';
 import type { ITextmodeLayer } from './interfaces/ITextmodeLayer';
 /**
  * A single layer within a multi-layered textmode rendering context.
@@ -27,31 +28,37 @@ export declare class TextmodeLayer implements ITextmodeLayer {
     $offsetY: number;
     /** @ignore */
     $rotation: number;
+    /** @ignore */
+    $fontSize: number | undefined;
+    /** @ignore */
+    $fontSource: string | TextmodeFont | URL | undefined;
     private _deps?;
-    private _drawFramebuffer?;
-    private _asciiFramebuffer?;
+    private _grid?;
+    private _font;
+    private _drawFramebuffer;
+    private _asciiFramebuffer;
     private _rawAsciiFramebuffer?;
+    private _pingPongBuffers?;
     private _drawCallback;
     private _hasRenderableContent;
-    private _ownsFramebuffers;
     private _filterQueue;
     /**
      * Create a new TextmodeLayer with the given options.
      * @param options Layer configuration options.
      * @ignore
      */
-    constructor(options?: TextmodeLayerOptions);
+    constructor(renderer: GLRenderer, options?: TextmodeLayerOptions);
     /**
-     * Return true when this layer has a user-provided draw callback.
+     * Attach necessary dependencies for this layer to function.
+     * @param deps Dependencies required by the layer.
      * @ignore
      */
-    $hasDraw(): boolean;
+    $attachDependencies(deps: LayerDependencies): Promise<void>;
     /**
-     * Get and clear the filter queue. Used by LayerManager for base layer filter processing.
-     * @returns The current filter queue, which is then cleared.
+     * Return true when this layer has a user-provided draw callback.
      * @ignore
      */
-    $consumeFilterQueue(): QueuedFilter[];
+    $hasDraw(): boolean;
     /**
      * Run the layer's draw callback in the calling context. This does NOT
      * manage framebuffer binding; the caller must ensure the correct
@@ -71,31 +78,55 @@ export declare class TextmodeLayer implements ITextmodeLayer {
     rotateZ(z?: number): number | void;
     filter<T extends BuiltInFilterName>(name: T, params?: BuiltInFilterParams[T]): void;
     filter(name: FilterName, params?: unknown): void;
+    /** Get or set the font size for this layer's font. */
+    fontSize(size?: number): number | void;
     /**
-     * Attach necessary dependencies for this layer to function.
-     * @param deps Dependencies required by the layer.
-     * @ignore
+     * Load a font into this layer from a URL/path or reuse an existing {@link TextmodeFont} instance.
+     * Creates a new font instance for this layer and loads the font data when a string source is provided.
+     *
+     * @param fontSource The URL or path to the font file.
+     * @returns The loaded TextmodeFont instance.
+     *
+     * @example
+     * ```javascript
+     * const layer = t.layers.add();
+     *
+     * t.setup(async () => {
+     *   // Load a custom font for this layer
+     *   await layer.loadFont('./fonts/custom.ttf');
+     * });
+     * ```
      */
-    $attachDependencies(deps: LayerDependencies): void;
+    loadFont(fontSource: string | TextmodeFont): Promise<TextmodeFont>;
     /**
      * Render the layer's content into its ASCII framebuffer.
      * @param textmodifier The Textmodifier instance.
      * @param conversionShader The shader used for conversion.
      * @ignore
      */
-    $render(textmodifier: Textmodifier, conversionShader: GLShader): void;
+    $render(textmodifier: Textmodifier, conversionShader: GLShader, options?: {
+        fallbackDraw?: () => void;
+    }): void;
     /**
      * Resize the layer's framebuffers to match the given grid dimensions.
      * @param grid The TextmodeGrid instance.
      * @ignore
      */
-    $resize(grid: TextmodeGrid): void;
+    $resize(): void;
     /**
      * Dispose of the layer's resources.
      * @ignore
      */
     $dispose(): void;
+    /**
+     * Get the texture containing the rendered textmode output for this layer.
+     */
     get texture(): WebGLTexture | undefined;
+    /**
+     * Get the grid associated with this layer.
+     */
+    get grid(): TextmodeGrid | undefined;
+    get font(): TextmodeFont;
     get width(): number;
     get height(): number;
     /**
@@ -103,6 +134,13 @@ export declare class TextmodeLayer implements ITextmodeLayer {
      * @ignore
      */
     get $hasRenderableContent(): boolean;
+    /**
+     * Get the framebuffer used for drawing operations on this layer.
+     */
     get drawFramebuffer(): GLFramebuffer | undefined;
-    private _initializeFramebuffers;
+    /**
+     * Get the framebuffer containing the rendered textmode output for this layer.
+     */
+    get asciiFramebuffer(): GLFramebuffer | undefined;
+    private _syncGridToFont;
 }

package/dist/types/textmode/layers/interfaces/ILayerManager.d.ts

@@ -1,5 +1,6 @@
 import type { TextmodeLayer } from '../TextmodeLayer';
 import type { TextmodeLayerOptions } from '../types';
+import type { TextmodeGrid } from '../../Grid';
 export interface ILayerManager {
     /**
      * Get all user layers as a readonly array.
@@ -40,4 +41,10 @@ export interface ILayerManager {
      * and layers need to be recreated from scratch.
      */
     clear(): void;
+    /**
+     * Get the grid of the topmost visible layer.
+     * Returns the topmost user layer's grid if any are visible, otherwise returns the base layer's grid.
+     * This is useful for input managers that need to map coordinates to the layer the user sees on top.
+     */
+    getTopmostGrid(): TextmodeGrid | undefined;
 }