textmode.js 0.9.0 → 0.9.1

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

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

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

@@ -0,0 +1,89 @@
+import type { GLRenderer, GLFramebuffer } from '../../rendering';
+import type { TextmodeLayer } from './TextmodeLayer';
+/**
+ * Parameters for the composite operation.
+ */
+export interface CompositeParams {
+    /** 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];
+    /** Canvas width in pixels. */
+    canvasWidth: number;
+    /** Canvas height in pixels. */
+    canvasHeight: number;
+}
+/**
+ * Represents the placement and sizing of a single layer within the composite operation.
+ * Used to position layers relative to the base canvas during compositing.
+ */
+export interface CompositeLayerPlacement {
+    /** The {@link TextmodeLayer} instance being composited. */
+    layer: TextmodeLayer;
+    /** The WebGL texture containing the layer's rendered content. */
+    texture: WebGLTexture;
+    /** The width of the layer's texture in pixels. */
+    width: number;
+    /** The height of the layer's texture in pixels. */
+    height: number;
+    /** The horizontal offset from the canvas origin in pixels. */
+    offsetX: number;
+    /** The vertical offset from the canvas origin in pixels. */
+    offsetY: number;
+}
+/**
+ * Handles the compositing of multiple layers using shader-based blending.
+ *
+ * This class is responsible for:
+ * - Managing ping-pong framebuffers for layer compositing
+ * - Applying blend modes via the composite shader
+ * - Rendering the final composited result to a target framebuffer
+ *
+ * @ignore
+ *
+ * @remarks
+ * The compositor uses a ping-pong buffer technique to avoid WebGL feedback loops
+ * when reading from and writing to textures during blend operations.
+ */
+export declare class Layer2DCompositor {
+    private readonly _renderer;
+    private readonly _blendShader;
+    private _pingPongBuffers;
+    private _currentPingPongIndex;
+    /**
+     * Create a new LayerCompositor.
+     * @param renderer The WebGL renderer instance.
+     * @param canvasWidth The canvas width in pixels.
+     * @param canvasHeight The canvas height in pixels.
+     */
+    constructor(renderer: GLRenderer, canvasWidth: number, canvasHeight: number);
+    /**
+     * Composite all layers onto the target framebuffer.
+     * @param params The composite parameters.
+     */
+    $composite(params: CompositeParams): void;
+    /**
+     * Blend a single layer onto the current composite.
+     */
+    private _blendLayer;
+    /**
+     * Copy the final composite result to the target framebuffer.
+     */
+    private _copyToTarget;
+    /**
+     * Resize the compositor's framebuffers.
+     * @param canvasWidth The canvas width in pixels.
+     * @param canvasHeight The canvas height in pixels.
+     * @ignore
+     */
+    $resize(canvasWidth: number, canvasHeight: number): void;
+    /**
+     * Dispose of all compositor resources.
+     * @ignore
+     */
+    $dispose(): void;
+}

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

@@ -0,0 +1,115 @@
+import type { GLFramebuffer } from '../../rendering';
+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';
+import { type FilterName, type BuiltInFilterName, type BuiltInFilterParams, TextmodeFilterManager } from '../filters';
+/**
+ * Manages the stack of layers within a {@link Textmodifier} instance.
+ *
+ * This interface provides methods to create, manage, and organize multiple textmode layers.
+ * Layers allow for complex compositing, independent rendering passes, and post-processing effects.
+ *
+ * The `base` layer is always present at the bottom of the stack. User-created layers are added
+ * on top of the base layer.
+ *
+ * Access this manager via `textmodifier.layers`.
+ */
+export declare class LayerManager implements ILayerManager {
+    private readonly _textmodifier;
+    private readonly _renderer;
+    private readonly _compositor2D;
+    private readonly _filterManager;
+    private readonly _layers;
+    private readonly _baseLayer;
+    private _isReady;
+    private readonly _gridDimensionChangeCallbacks;
+    private _globalFilterQueue;
+    private _preFilterFramebuffer;
+    private _postFilterFramebuffer;
+    /**
+     * Create a new LayerManager.
+     * @param textmodifier The Textmodifier instance this manager belongs to.
+     * @ignore
+     */
+    constructor(textmodifier: Textmodifier, opts: TextmodeOptions);
+    /**
+     * Initialize all pending layers, compositor, and global post-processing resources.
+     * @ignore
+     */
+    $initialize(): Promise<void>;
+    /**
+     * Queue a global filter to be applied after all layers are composited.
+     * Intended to be called by Textmodifier.filter().
+     * @ignore
+     */
+    $queueGlobalFilter<T extends BuiltInFilterName>(name: T, params?: BuiltInFilterParams[T]): void;
+    $queueGlobalFilter<TParams = unknown>(name: FilterName, params?: TParams): void;
+    /**
+     * Clear any queued global filters for the current frame.
+     * @ignore
+     */
+    $clearGlobalFilterQueue(): void;
+    add(options?: TextmodeLayerOptions): TextmodeLayer;
+    remove(layer: TextmodeLayer): void;
+    move(layer: TextmodeLayer, newIndex: number): void;
+    swap(layerA: TextmodeLayer, layerB: TextmodeLayer): void;
+    clear(): void;
+    /**
+     * Render all layers (base and user) and composite them to the provided target framebuffer.
+     * This performs ONLY layer rendering + compositing (no global filters, no present).
+     *
+     * @param targetFramebuffer The framebuffer to render the final composited result to.
+     * @ignore
+     */
+    $renderAndComposite(targetFramebuffer: GLFramebuffer): void;
+    /**
+     * Render, composite, apply global filters, present to screen, run post-draw hooks.
+     * This replaces the removed "Pass 3/4 + post hooks" section from Textmodifier.$render().
+     *
+     * @ignore
+     */
+    $renderAndPresent(): void;
+    /**
+     * Composite base + user layers onto the target framebuffer.
+     */
+    private _compositeLayers;
+    /**
+     * Resize all layers, compositor, and global post-processing buffers.
+     * @ignore
+     */
+    $resize(): void;
+    /**
+     * Dispose of the layer manager, all layers, compositor, and global post-processing resources.
+     * @ignore
+     */
+    $dispose(): void;
+    get all(): readonly TextmodeLayer[];
+    get base(): TextmodeLayer;
+    get filters(): TextmodeFilterManager;
+    get resultFramebuffer(): GLFramebuffer;
+    /**
+     * 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.
+     * @ignore
+     */
+    $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;
+    /**
+     * Notify all registered callbacks that a grid's dimensions have changed.
+     */
+    private _notifyGridDimensionChange;
+    /**
+     * Initialize a single layer with required dependencies.
+     */
+    private _initializeLayer;
+}

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

@@ -0,0 +1,105 @@
+import type { GLFramebuffer, GLRenderer, GLShader } from '../../rendering';
+import { TextmodeGrid } from '../Grid';
+import { TextmodeFont } from '../loadables/font';
+import type { Textmodifier } from '../Textmodifier';
+import type { TextmodeLayerBlendMode, TextmodeLayerOptions, LayerDependencies } from './types';
+import type { FilterName, BuiltInFilterName, BuiltInFilterParams } from '../filters';
+import type { ITextmodeLayer } from './interfaces/ITextmodeLayer';
+/**
+ * A single layer within a multi-layered textmode rendering context.
+ *
+ * Layers are composited together using various blend modes
+ * to create complex visual effects. Each layer can be independently
+ * manipulated in terms of visibility, {@link opacity}, {@link blendMode}, {@link offset}, rotation, {@link TextmodeGrid}, and {@link TextmodeFont}.
+ *
+ * You can draw on each layer by providing a draw callback function,
+ * like you would with the base layer's {@link Textmodifier.draw} method.
+ *
+ * Plugins can extend TextmodeLayer with additional methods using the plugin API's
+ * `extendLayer` function. For example, the `textmode-synth` plugin adds a `.synth()`
+ * method for hydra-like procedural generation.
+ */
+export declare class TextmodeLayer implements ITextmodeLayer {
+    /** @ignore */
+    $visible: boolean;
+    /** @ignore */
+    $opacity: number;
+    /** @ignore */
+    $blendMode: TextmodeLayerBlendMode;
+    /** @ignore */
+    $offsetX: number;
+    /** @ignore */
+    $offsetY: number;
+    /** @ignore */
+    $rotation: number;
+    /** @ignore */
+    $fontSize: number | undefined;
+    /** @ignore */
+    $fontSource: string | TextmodeFont | URL | undefined;
+    private _deps?;
+    private _grid?;
+    private _font;
+    private _drawFramebuffer;
+    private _asciiFramebuffer;
+    private _rawAsciiFramebuffer?;
+    private _pingPongBuffers?;
+    private _drawCallback;
+    private _filterQueue;
+    private _pluginState;
+    /**
+     * Create a new TextmodeLayer with the given options.
+     * @param renderer The TextmodeRenderer instance.
+     * @param options Layer configuration options.
+     * @ignore
+     */
+    constructor(renderer: GLRenderer, options?: TextmodeLayerOptions);
+    /**
+     * Attach necessary dependencies for this layer to function.
+     * @param deps Dependencies required by the layer.
+     * @ignore
+     */
+    $attachDependencies(deps: LayerDependencies): Promise<void>;
+    draw(callback: () => void): void;
+    show(): void;
+    hide(): void;
+    opacity(opacity?: number): number | void;
+    blendMode(mode?: TextmodeLayerBlendMode): TextmodeLayerBlendMode | void;
+    offset(x?: number, y?: number): {
+        x: number;
+        y: number;
+    } | void;
+    rotateZ(z?: number): number | void;
+    filter<T extends BuiltInFilterName>(name: T, params?: BuiltInFilterParams[T]): void;
+    filter<TParams = unknown>(name: FilterName, params?: TParams): void;
+    setPluginState<T>(pluginName: string, state: T): void;
+    getPluginState<T>(pluginName: string): T | undefined;
+    hasPluginState(pluginName: string): boolean;
+    deletePluginState(pluginName: string): boolean;
+    fontSize(size?: number): number | 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;
+    /**
+     * Resize the layer's framebuffers to match the given grid dimensions.
+     * @ignore
+     */
+    $resize(): void;
+    /**
+     * Dispose of the layer's resources.
+     * @ignore
+     */
+    $dispose(): void;
+    get texture(): WebGLTexture | undefined;
+    get grid(): TextmodeGrid | undefined;
+    get font(): TextmodeFont;
+    get width(): number;
+    get height(): number;
+    get drawFramebuffer(): GLFramebuffer | undefined;
+    get asciiFramebuffer(): GLFramebuffer | undefined;
+    private _syncGridToFont;
+}

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

@@ -0,0 +1,4 @@
+export { TextmodeLayer } from './TextmodeLayer';
+export { LayerManager as TextmodeLayerManager } from './LayerManager';
+export { Layer2DCompositor as LayerCompositor } from './Layer2DCompositor';
+export type { TextmodeLayerOptions, TextmodeLayerBlendMode } from './types';

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

@@ -0,0 +1,158 @@
+import type { TextmodeLayer } from '../TextmodeLayer';
+import type { TextmodeLayerOptions } from '../types';
+import type { TextmodeGrid } from '../../Grid';
+import type { GLFramebuffer } from '../../../rendering/webgl/core/Framebuffer';
+export interface ILayerManager {
+    /**
+     * Get all user layers as a readonly array.
+     *
+     * @example
+     * ```js
+     * const t = textmode.create();
+     * t.layers.add();
+     * t.layers.add();
+     *
+     * console.log(t.layers.all.length); // 2
+     *
+     * // Iterate over all user layers
+     * t.layers.all.forEach(layer => {
+     *   layer.opacity(0.5);
+     * });
+     * ```
+     */
+    readonly all: readonly TextmodeLayer[];
+    /**
+     * The base layer that is always rendered at the bottom of the layer stack.
+     * This layer represents the main drawing content before any user layers are composited.
+     *
+     * The base layer cannot be removed or moved.
+     */
+    readonly base: TextmodeLayer;
+    /**
+     * The framebuffer containing the final composited result after all layers and filters have been applied.
+     */
+    readonly resultFramebuffer: GLFramebuffer;
+    /**
+     * Create and add a new layer to the top of the layer stack.
+     *
+     * New layers are initialized with their own grid and font settings.
+     * Layers can be offset, rotated, and blended with layers below them.
+     *
+     * @param options Optional configuration for the new layer (visibility, opacity, blendMode, etc.)
+     * @returns The newly created TextmodeLayer instance.
+     *
+     * @example
+     * ```javascript
+     * const t = textmode.create();
+     *
+     * // Add a new layer on top of the base layer
+     * const uiLayer = t.layers.add({
+     *     blendMode: 'normal',
+     *     opacity: 1.0,
+     *     fontSize: 16
+     * });
+     *
+     * // Draw to the new layer
+     * uiLayer.draw(() => {
+     *     t.clear(); // Clear THIS layer's background (transparent)
+     *
+     *     t.charColor(255, 0, 0); // Red text
+     *     t.cellColor(0, 0, 0, 0); // Transparent cell background
+     *     t.char('!');
+     *     t.rect(5, 5);
+     * });
+     *
+     * // Base layer content
+     * t.draw(() => {
+     *     t.background(0, 0, 50); // Dark blue background
+     *
+     *     t.charColor(0, 0, 255); // Blue text
+     *     t.cellColor(0, 0, 0, 0); // Transparent cell background
+     *     t.char('?');
+     *     t.rect(5, 5);
+     * });
+     * ```
+     */
+    add(options?: TextmodeLayerOptions): TextmodeLayer;
+    /**
+     * Remove a layer from the manager.
+     * @param layer The layer to remove.
+     *
+     * @example
+     * ```js
+     * const t = textmode.create();
+     *
+     * const tempLayer = t.layers.add();
+     *
+     * // Remove the layer after 100 frames
+     * t.draw(() => {
+     *   if (t.frameCount > 100) {
+     *     t.layers.remove(tempLayer);
+     *   }
+     * });
+     * ```
+     */
+    remove(layer: TextmodeLayer): void;
+    /**
+     * Move a layer to a new index in the layer stack.
+     * @param layer The layer to move.
+     * @param newIndex The new index for the layer.
+     *
+     * @example
+     * ```js
+     * const t = textmode.create();
+     *
+     * const bgLayer = t.layers.add(); // Index 0
+     * const fgLayer = t.layers.add(); // Index 1
+     *
+     * // Swap z-order by moving fgLayer to bottom (index 0)
+     * // This pushes bgLayer to index 1
+     * t.layers.move(fgLayer, 0);
+     * ```
+     */
+    move(layer: TextmodeLayer, newIndex: number): void;
+    /**
+     * Swap the order of two layers if they exist in the same collection.
+     * @param layerA The first layer to swap.
+     * @param layerB The second layer to swap.
+     *
+     * @example
+     * ```js
+     * const t = textmode.create();
+     *
+     * const layer1 = t.layers.add();
+     * const layer2 = t.layers.add();
+     *
+     * // Swap the layers' positions in the stack
+     * t.layers.swap(layer1, layer2);
+     * ```
+     */
+    swap(layerA: TextmodeLayer, layerB: TextmodeLayer): void;
+    /**
+     * Remove all user-created layers from the manager.
+     * The base layer is not affected by this operation.
+     * This is useful for integration into live-coding environments where code is re-evaluated
+     * and layers need to be recreated from scratch.
+     *
+     * @example
+     * ```js
+     * const t = textmode.create();
+     *
+     * t.setup(() => {
+     *   // Ensure clean slate when re-running setup
+     *   t.layers.clear();
+     *
+     *   // Re-create layers
+     *   t.layers.add({ blendMode: 'additive' });
+     *   t.layers.add({ blendMode: 'multiply' });
+     * });
+     * ```
+     */
+    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;
+}