textmode.js 0.7.0-beta.1 → 0.7.0-beta.3

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

@@ -0,0 +1,323 @@
+import type { GLFramebuffer } from '../../../rendering';
+import type { TextmodeLayerBlendMode } from '../types';
+import type { FilterName, BuiltInFilterName, BuiltInFilterParams } from '../../filters';
+/**
+ * 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, opacity, blend mode, and position.
+ *
+ * You can draw on each layer by providing a draw callback function,
+ * like you would with the base layer's {@link Textmodifier.draw} method.
+ *
+ * You can also apply a sequence of post-processing filters to each layer's
+ * rendered output using the {@link ITextmodeLayer.filter} method.
+ *
+ * The base layer, which is always present at the bottom of the layer stack,
+ * can be accessed via {@link Textmodifier.baseLayer}.
+ */
+export interface ITextmodeLayer {
+    /**
+     * Returns the WebGL texture of the final ASCII framebuffer.
+     * If the layer is not yet initialized, returns undefined.
+     */
+    readonly texture: WebGLTexture | undefined;
+    /**
+     * Returns the width of the final ASCII framebuffer in pixels.
+     * If the layer is not yet initialized, returns 0.
+     */
+    readonly width: number;
+    /**
+     * Returns the height of the final ASCII framebuffer in pixels.
+     * If the layer is not yet initialized, returns 0.
+     */
+    readonly height: number;
+    /**
+     * Returns the draw framebuffer for this layer.
+     * If the layer is not yet initialized, returns undefined.
+     */
+    readonly drawFramebuffer: GLFramebuffer | undefined;
+    /**
+     * Define this layer's draw callback. The callback is executed each frame
+     * and should contain all drawing commands for this layer.
+     *
+     * Inside the callback, use `t` (your textmode instance) to access drawing
+     * methods like `char()`, `charColor()`, `translate()`, and `rect()`.
+     *
+     * @param callback The function to call when drawing this layer.
+     *
+     * @example
+     * ```typescript
+     * const t = textmode.create();
+     *
+     * // Create layers with different blend modes
+     * const glowLayer = t.layers.add({ blendMode: 'additive', opacity: 0.7 });
+     * const particleLayer = t.layers.add({ blendMode: 'screen', opacity: 0.5 });
+     *
+     * // Base layer: animated background with subtle wave pattern
+     * t.draw(() => {
+     *   const time = t.frameCount * 0.02;
+     *   t.background(8, 12, 24);
+     *
+     *   // Draw undulating grid pattern
+     *   for (let y = -t.grid.rows / 2; y < t.grid.rows / 2; y++) {
+     *     for (let x = -t.grid.cols / 2; x < t.grid.cols / 2; x++) {
+     *       const wave = Math.sin(x * 0.3 + time) * Math.cos(y * 0.3 + time * 0.7);
+     *       const brightness = 20 + wave * 15;
+     *
+     *       t.push();
+     *       t.charColor(brightness, brightness + 5, brightness + 15);
+     *       t.char(wave > 0.3 ? '+' : wave > -0.3 ? '·' : '.');
+     *       t.translate(x, y);
+     *       t.point();
+     *       t.pop();
+     *     }
+     *   }
+     * });
+     *
+     * // Glow layer: pulsing orbital ring
+     * glowLayer.draw(() => {
+     *   t.clear();
+     *   const time = t.frameCount * 0.03;
+     *   const ringCount = 24;
+     *
+     *   for (let i = 0; i < ringCount; i++) {
+     *     const angle = (i / ringCount) * Math.PI * 2 + time;
+     *     const pulse = Math.sin(time * 2 + i * 0.5) * 0.5 + 0.5;
+     *     const radius = 8 + Math.sin(time * 1.5) * 2;
+     *
+     *     t.push();
+     *     t.charColor(255, 180 + pulse * 75, 80 + pulse * 100);
+     *     t.char('#*+=-'[i % 5]);
+     *     t.translate(Math.round(Math.cos(angle) * radius), Math.round(Math.sin(angle) * radius * 0.6));
+     *     t.point();
+     *     t.pop();
+     *   }
+     * });
+     *
+     * // Particle layer: floating sparkles
+     * particleLayer.draw(() => {
+     *   t.clear();
+     *   const time = t.frameCount * 0.015;
+     *
+     *   for (let i = 0; i < 12; i++) {
+     *     const seed = i * 137.5; // Golden angle for distribution
+     *     const x = Math.sin(seed + time) * (6 + i * 0.8);
+     *     const y = Math.cos(seed * 1.3 + time * 0.8) * (4 + i * 0.5);
+     *     const flicker = Math.sin(time * 4 + i) * 0.5 + 0.5;
+     *
+     *     t.push();
+     *     t.charColor(200 + flicker * 55, 220, 255);
+     *     t.char('*');
+     *     t.translate(Math.round(x), Math.round(y));
+     *     t.point();
+     *     t.pop();
+     *   }
+     * });
+     * ```
+     */
+    draw(callback: () => void): void;
+    /**
+     * Show this layer for rendering.
+     */
+    show(): void;
+    /**
+     * Hide this layer from rendering.
+     */
+    hide(): void;
+    /**
+     * Define or retrieve the layer's opacity.
+     * @param opacity The opacity value to set (between 0 and 1).
+     * @returns The current opacity if no parameter is provided.
+     */
+    opacity(opacity?: number): number | void;
+    /**
+     * Set or get the layer's blend mode for compositing with layers below.
+     *
+     * @param mode The blend mode to set.
+     * @returns The current blend mode if no parameter is provided.
+     *
+     * **Available Blend Modes:**
+     * - `'normal'` - Standard alpha compositing
+     * - `'additive'` - Adds colors together (great for glow/energy effects)
+     * - `'multiply'` - Darkens by multiplying colors
+     * - `'screen'` - Lightens; inverse of multiply
+     * - `'subtract'` - Subtracts layer from base
+     * - `'darken'` - Takes minimum of each channel
+     * - `'lighten'` - Takes maximum of each channel
+     * - `'overlay'` - Combines multiply/screen for contrast
+     * - `'softLight'` - Subtle contrast enhancement
+     * - `'hardLight'` - Intense overlay effect
+     * - `'colorDodge'` - Brightens base by blend color
+     * - `'colorBurn'` - Darkens base by blend color
+     * - `'difference'` - Absolute difference; creates inverted effects
+     * - `'exclusion'` - Softer difference effect
+     *
+     * @example
+     * ```typescript
+     * const t = textmode.create();
+     *
+     * // Create 5 layers with different blend modes
+     * const blendModes = ['additive', 'screen', 'overlay', 'difference', 'multiply'];
+     * const colors = [[255, 80, 150], [80, 180, 255], [255, 200, 80], [150, 255, 120], [200, 120, 255]];
+     * const layers = blendModes.map(mode => t.layers.add({ blendMode: mode, opacity: 0.85 }));
+     *
+     * t.draw(() => {
+     *     const time = t.frameCount * 0.2;
+     *     t.background(12, 8, 20, 255);
+     *
+     *     layers.forEach((layer, i) => {
+     *         layer.draw(() => {
+     *             t.charColor(...colors[i], 255);
+     *
+     *             // Draw spiral of characters
+     *             for (let j = 0; j < 30; j++) {
+     *                 const angle = j * 0.2 + time * (i % 2 ? 1 : -1);
+     *                 const radius = 3 + j * 0.4 + Math.sin(time + j) * 2;
+     *                 const x = Math.cos(angle) * radius;
+     *                 const y = Math.sin(angle) * radius * 0.6;
+     *
+     *                 t.char('#*+=-.'[j % 6]);
+     *                 t.translate(Math.round(x), Math.round(y));
+     *                 t.rect(1, 1);
+     *             }
+     *         });
+     *
+     *         // Offset each layer
+     *         layer.offset(Math.sin(time * 0.6 + i) * 6, Math.cos(time * 0.3 + i) * 4);
+     *     });
+     * });
+     * ```
+     */
+    blendMode(mode: TextmodeLayerBlendMode): TextmodeLayerBlendMode | void;
+    /**
+     * Set or get the layer's offset in pixels.
+     * @param x The x offset in pixels.
+     * @param y The y offset in pixels.
+     * @returns The current offset if no parameters are provided.
+     *
+     * @example
+     * ```typescript
+     * const t = textmode.create();
+     *
+     * const LAYER_COUNT = 32;
+     * const LABEL = 'textmode.js';
+     *
+     * // Create trailing layers
+     * const layers = Array.from({ length: LAYER_COUNT }, () =>
+     *   t.layers.add({ blendMode: 'normal', opacity: 1.0 })
+     * );
+     *
+     * // Snake segments for smooth trailing effect
+     * const segments = Array.from({ length: LAYER_COUNT + 1 }, () => ({ x: 0, y: 0 }));
+     *
+     * // Helper to draw text label centered
+     * const drawLabel = (color) => {
+     *   t.charColor(...color);
+     *   t.cellColor(0, 0, 0, 0);
+     *   [...LABEL].forEach((char, i) => {
+     *     t.push();
+     *     t.char(char);
+     *     t.translate(i - Math.floor(LABEL.length / 2), 0);
+     *     t.rect(1, 1);
+     *     t.pop();
+     *   });
+     * };
+     *
+     * // Set up layer draw callbacks
+     * layers.forEach((layer, index) => {
+     *   layer.draw(() => {
+     *     t.background(0, 0, 0, 0);
+     *     const brightness = 255 - (index / LAYER_COUNT) * 180;
+     *     drawLabel([brightness, brightness * 0.8, 255]);
+     *   });
+     * });
+     *
+     * t.draw(() => {
+     *   t.background(20, 20, 40);
+     *   t.clear();
+     *
+     *   // Compute head position (circular motion)
+     *   const time = t.frameCount * 0.06;
+     *   const head = {
+     *     x: Math.cos(time) * 24,
+     *     y: Math.sin(time * 0.7) * 12
+     *   };
+     *
+     *   // Update snake segments with elastic follow
+     *   segments[0] = head;
+     *   for (let i = 1; i < segments.length; i++) {
+     *     const prev = segments[i - 1];
+     *     segments[i].x += (prev.x - segments[i].x) * 0.3;
+     *     segments[i].y += (prev.y - segments[i].y) * 0.3;
+     *   }
+     *
+     *   // Draw head on base layer
+     *   t.layers.base.offset(Math.round(head.x), Math.round(head.y));
+     *   drawLabel([255, 200, 100]);
+     *
+     *   // Offset each trailing layer to its segment position
+     *   layers.forEach((layer, index) => {
+     *     const seg = segments[index + 1];
+     *     layer.offset(Math.round(seg.x), Math.round(seg.y));
+     *   });
+     * });
+     * ```
+     */
+    offset(x?: number, y?: number): {
+        x: number;
+        y: number;
+    } | void;
+    /**
+     * Apply a post-processing filter to this layer's rendered output.
+     *
+     * Filters are applied after ASCII conversion in the order they are called.
+     * Call this method within your layer's draw callback to apply effects.
+     *
+     * **Built-in Filters:**
+     * - `'invert'` - Inverts all colors
+     * - `'grayscale'` - Converts to grayscale (param: amount 0-1, default 1)
+     * - `'sepia'` - Applies sepia tone (param: amount 0-1, default 1)
+     * - `'threshold'` - Black/white threshold (param: threshold 0-1, default 0.5)
+     *
+     * @param name The name of the filter to apply (built-in or custom registered filter)
+     * @param params Optional parameters for the filter
+     *
+     * @example
+     * ```typescript
+     * const t = textmode.create();
+     *
+     * // Create a layer with filters applied
+     * const effectLayer = t.layers.add({ blendMode: 'normal', opacity: 1.0 });
+     *
+     * t.draw(() => {
+     *   // Base layer: draw a simple pattern
+     *   t.background(20, 20, 40);
+     *   t.charColor(255, 200, 100);
+     *   t.char('#');
+     *   t.rect(t.grid.cols, t.grid.rows);
+     * });
+     *
+     * effectLayer.draw(() => {
+     *   t.clear();
+     *   t.charColor(100, 150, 255);
+     *   t.char('*');
+     *   t.rect(10, 10);
+     *
+     *   // Apply filters in sequence
+     *   if (t.frameCount % 120 < 60) {
+     *     effectLayer.filter('invert');
+     *   }
+     *   effectLayer.filter('grayscale', Math.sin(t.frameCount * 0.05) * 0.5 + 0.5);
+     * });
+     * ```
+     */
+    filter<T extends BuiltInFilterName>(name: FilterName, params?: BuiltInFilterParams[T]): void;
+    /**
+     * Apply a custom filter registered via `t.layers.filters.register()`.
+     * @param name The name of the custom filter
+     * @param params Optional parameters for the custom filter
+     */
+    filter(name: FilterName, params?: unknown): void;
+}

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

@@ -2,7 +2,7 @@ import type { GLFramebuffer } from '../../rendering';
 import type { TextmodeGrid } from '../Grid';
 import type { GLRenderer } from '../../rendering/webgl/core/Renderer';
 import type { TextmodeFont } from '../loadables/font';
-import type { LayerFilterManager } from './filters';
+import type { TextmodeFilterManager } from '../filters';
 /**
  * Blend modes available for {@link TextmodeLayer} compositing in 2D mode.
  *
@@ -59,7 +59,12 @@ export interface LayerDependencies {
     /**
      * The shared filter manager for applying post-ASCII filters.
      */
-    filterManager: LayerFilterManager;
+    filterManager: TextmodeFilterManager;
+    /**
+     * Ping-pong buffers for layer filter chain processing (grid-sized).
+     * Shared across all layers within the LayerManager.
+     */
+    layerPingPongBuffers: [GLFramebuffer, GLFramebuffer];
     /**
      * Optional external draw framebuffer. When provided, the layer will use this
      * instead of creating its own. Used for the base layer which shares the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "textmode.js",
-  "version": "0.7.0-beta.1",
+  "version": "0.7.0-beta.3",
   "description": "textmode.js is a lightweight creative coding library for creating real-time ASCII art on the web.",
   "type": "module",
   "types": "./dist/types/index.d.ts",

package/dist/types/textmode/layers/filters/FilterRegistry.d.ts

@@ -1,87 +0,0 @@
-import type { TextmodeFilterStrategy, FilterName } from './types';
-/**
- * Register a custom filter strategy.
- *
- * Once registered, the filter can be used with `layer.filter('filterId', params)`.
- *
- * @param strategy The filter strategy to register
- * @throws Error if a filter with the same ID is already registered
- *
- * @example
- * ```typescript
- * import { registerFilterStrategy } from 'textmode.js';
- *
- * registerFilterStrategy({
- *     id: 'customGlow',
- *     createShader(context) {
- *         return context.renderer.$createShader(vertexSrc, fragmentSrc);
- *     },
- *     createUniforms(params, context) {
- *         return {
- *             u_intensity: params?.intensity ?? 1.0,
- *             u_color: params?.color ?? [1, 1, 1],
- *             u_resolution: [context.width, context.height]
- *         };
- *     }
- * });
- *
- * // Then in your sketch:
- * layer.draw(() => {
- *     // ... drawing code
- *     this.filter('customGlow', { intensity: 0.8, color: [1, 0.5, 0] });
- * });
- * ```
- */
-export declare function registerFilterStrategy(strategy: TextmodeFilterStrategy): void;
-/**
- * Unregister a previously registered filter strategy.
- *
- * @param id The ID of the filter to unregister
- * @returns true if the filter was unregistered, false if it wasn't registered
- *
- * @example
- * ```typescript
- * import { unregisterFilterStrategy } from 'textmode.js';
- *
- * unregisterFilterStrategy('customGlow');
- * ```
- */
-export declare function unregisterFilterStrategy(id: FilterName): boolean;
-/**
- * Get a registered filter strategy by its ID.
- *
- * @param id The ID of the filter
- * @returns The filter strategy, or undefined if not found
- * @internal
- */
-export declare function getFilterStrategy(id: FilterName): TextmodeFilterStrategy | undefined;
-/**
- * Check if a filter is registered.
- *
- * @param id The ID of the filter to check
- * @returns true if the filter is registered
- *
- * @example
- * ```typescript
- * import { isFilterRegistered } from 'textmode.js';
- *
- * if (isFilterRegistered('myFilter')) {
- *     layer.filter('myFilter');
- * }
- * ```
- */
-export declare function isFilterRegistered(id: FilterName): boolean;
-/**
- * Get a list of all registered filter IDs.
- *
- * @returns An array of all registered filter IDs
- *
- * @example
- * ```typescript
- * import { getRegisteredFilters } from 'textmode.js';
- *
- * console.log('Available filters:', getRegisteredFilters());
- * // ['invert', 'grayscale', 'sepia', 'hueRotate', ...]
- * ```
- */
-export declare function getRegisteredFilters(): FilterName[];

package/dist/types/textmode/layers/filters/LayerFilterManager.d.ts

@@ -1,71 +0,0 @@
-import type { GLRenderer, GLFramebuffer } from '../../../rendering';
-import type { QueuedFilter } from './types';
-/**
- * Manages filter shader compilation and application for layers.
- *
- * This manager:
- * - Lazily compiles filter shaders on first use
- * - Uses ping-pong rendering to chain multiple filters
- * - Caches compiled shaders for performance
- *
- * @internal
- */
-export declare class LayerFilterManager {
-    private readonly _renderer;
-    private readonly _shaderCache;
-    private readonly _copyShader;
-    private _pingPongBuffers;
-    private _currentBufferIndex;
-    private _isInitialized;
-    /**
-     * Create a new LayerFilterManager.
-     * @param renderer The WebGL renderer instance
-     */
-    constructor(renderer: GLRenderer);
-    /**
-     * Initialize ping-pong buffers for filter chain processing.
-     * @param width Buffer width in pixels
-     * @param height Buffer height in pixels
-     */
-    $initialize(width: number, height: number): void;
-    /**
-     * Apply a chain of filters to the source texture, outputting to target.
-     *
-     * @param sourceTexture The input texture (raw ASCII framebuffer)
-     * @param targetFramebuffer The output framebuffer (layer's ASCII framebuffer)
-     * @param filters The queue of filters to apply in order
-     * @param width Framebuffer width
-     * @param height Framebuffer height
-     */
-    $applyFilters(sourceTexture: WebGLTexture, targetFramebuffer: GLFramebuffer, filters: QueuedFilter[], width: number, height: number): void;
-    /**
-     * Apply a single filter pass.
-     */
-    private _applyFilter;
-    /**
-     * Get or create a cached shader for the given filter.
-     */
-    private _getOrCreateShader;
-    /**
-     * Copy a texture to a framebuffer using the copy shader.
-     */
-    private _copyTexture;
-    /**
-     * Get the next ping-pong buffer (not currently in use).
-     */
-    private _getNextBuffer;
-    /**
-     * Swap to the next ping-pong buffer.
-     */
-    private _swapBuffers;
-    /**
-     * Resize the ping-pong buffers.
-     * @param width New width in pixels
-     * @param height New height in pixels
-     */
-    $resize(width: number, height: number): void;
-    /**
-     * Dispose of all resources.
-     */
-    $dispose(): void;
-}