textmode.js 0.6.1 → 0.7.0-beta.2

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

@@ -0,0 +1,74 @@
+import type { GLRenderer, GLShader, GLFramebuffer } from '../../../rendering';
+import type { QueuedFilter, FilterName } 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;
+    private _filterRegistry;
+    /**
+     * Create a new LayerFilterManager.
+     * @param renderer The WebGL renderer instance
+     */
+    constructor(renderer: GLRenderer);
+    register(id: FilterName, shader: GLShader | string, uniformDefs?: Record<string, [paramName: string, defaultValue: unknown]>): Promise<void>;
+    unregister(id: FilterName): boolean;
+    /**
+     * 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;
+}

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

@@ -0,0 +1,3 @@
+export type { FilterName, BuiltInFilterName, BuiltInFilterParams, QueuedFilter, FilterContext, TextmodeFilterStrategy } from './types';
+export { FilterRegistry } from './FilterRegistry';
+export { LayerFilterManager } from './LayerFilterManager';

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

@@ -0,0 +1,123 @@
+import type { GLShader } from '../../../rendering';
+import type { GLRenderer } from '../../../rendering/webgl/core/Renderer';
+/**
+ * Built-in filter names provided by textmode.js
+ */
+export type BuiltInFilterName = 'invert' | 'grayscale' | 'sepia' | 'hueRotate' | 'saturate' | 'brightness' | 'contrast' | 'threshold' | 'chromaticAberration' | 'pixelate';
+/**
+ * Filter name type that allows both built-in and custom filter names
+ */
+export type FilterName = BuiltInFilterName | (string & {});
+/**
+ * Filter parameter types for built-in filters.
+ *
+ * Most filters accept either a single number (for the primary parameter)
+ * or an object with named properties.
+ */
+export interface BuiltInFilterParams {
+    /** Inverts all colors (no params needed) */
+    invert: void;
+    /** Converts to grayscale. Amount: 0-1, default 1 */
+    grayscale: number | {
+        amount?: number;
+    } | void;
+    /** Applies sepia tone. Amount: 0-1, default 1 */
+    sepia: number | {
+        amount?: number;
+    } | void;
+    /** Rotates hue. Angle in degrees */
+    hueRotate: number | {
+        angle?: number;
+    };
+    /** Adjusts saturation. Amount: 1 = normal, >1 = more saturated */
+    saturate: number | {
+        amount?: number;
+    };
+    /** Adjusts brightness. Amount: 1 = normal, >1 = brighter */
+    brightness: number | {
+        amount?: number;
+    };
+    /** Adjusts contrast. Amount: 1 = normal, >1 = more contrast */
+    contrast: number | {
+        amount?: number;
+    };
+    /** Black/white threshold. Threshold: 0-1 */
+    threshold: number | {
+        threshold?: number;
+    };
+    /** Chromatic aberration (color fringing) */
+    chromaticAberration: number | {
+        amount?: number;
+        direction?: [number, number];
+    };
+    /** Pixelate effect. PixelSize in pixels */
+    pixelate: number | {
+        pixelSize?: number;
+    };
+}
+/**
+ * A queued filter operation to be applied during rendering
+ * @internal
+ */
+export interface QueuedFilter {
+    name: FilterName;
+    params: unknown;
+}
+/**
+ * Context provided to filter strategies for shader creation
+ */
+export interface FilterContext {
+    /** The WebGL renderer instance */
+    renderer: GLRenderer;
+    /** The WebGL2 rendering context */
+    gl: WebGL2RenderingContext;
+    /** Width of the framebuffer being filtered */
+    width: number;
+    /** Height of the framebuffer being filtered */
+    height: number;
+}
+/**
+ * Interface for implementing custom filter strategies.
+ *
+ * Custom filters can be registered using {@link registerFilterStrategy} and will
+ * be available for use with `layer.filter('myFilter', params)`.
+ *
+ * @example
+ * ```typescript
+ * import { registerFilterStrategy } from 'textmode.js';
+ *
+ * const myCustomFilter: TextmodeFilterStrategy = {
+ *     id: 'myFilter',
+ *     createShader(context) {
+ *         return context.renderer.$createShader(vertexSource, fragmentSource);
+ *     },
+ *     createUniforms(params, context) {
+ *         return {
+ *             u_intensity: params?.intensity ?? 1.0,
+ *             u_resolution: [context.width, context.height]
+ *         };
+ *     }
+ * };
+ *
+ * registerFilterStrategy(myCustomFilter);
+ * ```
+ */
+export interface TextmodeFilterStrategy {
+    /** Unique identifier for this filter */
+    readonly id: FilterName;
+    /**
+     * Create the shader program for this filter.
+     * Called once when the filter is first used (lazy initialization).
+     * @param context The filter context containing renderer and dimensions
+     * @returns The compiled shader program
+     */
+    createShader(context: FilterContext): GLShader;
+    /**
+     * Create uniform values for this filter based on user parameters.
+     * Called each time the filter is applied.
+     * @param params The parameters passed by the user (can be undefined)
+     * @param context The filter context containing dimensions
+     * @returns An object mapping uniform names to values
+     */
+    createUniforms(params: unknown, context: FilterContext): Record<string, unknown>;
+}

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

@@ -0,0 +1,6 @@
+export { TextmodeLayer } from './TextmodeLayer';
+export { LayerManager as TextmodeLayerManager } from './LayerManager';
+export { Layer2DCompositor as LayerCompositor } from './Layer2DCompositor';
+export type { TextmodeLayerOptions, TextmodeLayerBlendMode } from './types';
+export { FilterRegistry } from './filters';
+export type { FilterName, BuiltInFilterName, BuiltInFilterParams, FilterContext, TextmodeFilterStrategy } from './filters';

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

@@ -0,0 +1,74 @@
+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';
+/**
+ * Blend modes available for {@link TextmodeLayer} compositing in 2D mode.
+ *
+ * - `'normal'`: Standard alpha compositing. Opaque layer pixels fully replace the base; translucent pixels fade in.
+ * - `'additive'`: Layer color is added on top of the base. Great for glow/energy effects but will clip as values approach white.
+ * - `'multiply'`: `result = layer * base`. Darkens wherever both layers have color; any channel multiplied by 0 becomes 0.
+ * - `'screen'`: Inverse of multiply. `result = 1 - (1 - layer) * (1 - base)`. Preserves highlights while lightening midtones.
+ * - `'subtract'`: `result = base - layer`. Useful for cutting out or darkening effects.
+ * - `'darken'`: Takes the minimum of layer and base per channel. Only darkens; never lightens.
+ * - `'lighten'`: Takes the maximum of layer and base per channel. Only lightens; never darkens.
+ * - `'overlay'`: Combines multiply and screen. Darkens darks and lightens lights, increasing contrast.
+ * - `'softLight'`: Softer version of overlay. Subtle contrast enhancement.
+ * - `'hardLight'`: Like overlay but more intense. Uses blend color to determine multiply/screen.
+ * - `'colorDodge'`: Brightens the base by the blend color. Creates intense highlights.
+ * - `'colorBurn'`: Darkens the base by the blend color. Creates deep shadows.
+ * - `'difference'`: `result = |base - blend|`. Creates inverted/solarized effects.
+ * - `'exclusion'`: Softer version of difference. `result = base + blend - 2 * base * blend`.
+ */
+export type TextmodeLayerBlendMode = 'normal' | 'additive' | 'multiply' | 'screen' | 'subtract' | 'darken' | 'lighten' | 'overlay' | 'softLight' | 'hardLight' | 'colorDodge' | 'colorBurn' | 'difference' | 'exclusion';
+/**
+ * Options for configuring a new TextmodeLayer via {@link TextmodeLayerManager.add}.
+ */
+export interface TextmodeLayerOptions {
+    /**
+     * Whether the layer is visible. Default is `true`.
+     */
+    visible?: boolean;
+    /**
+     * The opacity of the layer, between 0 (fully transparent) and 1 (fully opaque). Default is `1`.
+     */
+    opacity?: number;
+    /**
+     * The blend mode used when rendering this layer. Default is `'normal'`.
+     */
+    blendMode?: TextmodeLayerBlendMode;
+    /**
+     * The horizontal offset of the layer in pixels. Default is `0`.
+     */
+    offsetX?: number;
+    /**
+     * The vertical offset of the layer in pixels. Default is `0`.
+     */
+    offsetY?: number;
+}
+/**
+ * Dependencies required by a TextmodeLayer to function.
+ * @internal
+ */
+export interface LayerDependencies {
+    renderer: GLRenderer;
+    grid: TextmodeGrid;
+    font: TextmodeFont;
+    createFramebuffer: (width: number, height: number, attachments?: number) => GLFramebuffer;
+    /**
+     * The shared filter manager for applying post-ASCII filters.
+     */
+    filterManager: LayerFilterManager;
+    /**
+     * Optional external draw framebuffer. When provided, the layer will use this
+     * instead of creating its own. Used for the base layer which shares the
+     * main textmode draw framebuffer.
+     */
+    externalDrawFramebuffer?: GLFramebuffer;
+    /**
+     * Optional external ASCII framebuffer. When provided, the layer will use this
+     * instead of creating its own. Used for the base layer.
+     */
+    externalAsciiFramebuffer?: GLFramebuffer;
+}

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

@@ -68,7 +68,7 @@ export declare class LoadingScreenManager {
      * Get the current overall loading progress (0-1).
     *
     * @example
-    * ```ts
+    * ```javascript
     * const t = textmode.create({
     *   width: 800,
     *   height: 600,
@@ -92,7 +92,7 @@ export declare class LoadingScreenManager {
      * @returns The current loading screen message.
     *
     * @example
-    * ```ts
+    * ```javascript
     * const t = textmode.create({
     *   width: 800,
     *   height: 600,
@@ -121,7 +121,7 @@ export declare class LoadingScreenManager {
      * @returns A handle to the created loading phase.
     *
     * @example
-    * ```ts
+    * ```javascript
     * const t = textmode.create({
     *   width: 800,
     *   height: 600,
@@ -162,7 +162,7 @@ export declare class LoadingScreenManager {
      * @param error The error message or `Error` object.
     *
     * @example
-    * ```ts
+    * ```javascript
     * const t = textmode.create({
     *   width: 800,
     *   height: 600,

package/dist/types/textmode/managers/MouseManager.d.ts

@@ -1,7 +1,12 @@
 import type { TextmodeCanvas } from '../Canvas';
 import type { TextmodeGrid } from '../Grid';
 /**
- * Mouse coordinates in grid space
+ * Mouse coordinates in grid space.
+ *
+ * Unlike the main drawing logic, where `(0,0,0)` is the center cell,
+ * the mouse coordinates use the top-left cell as `(0,0)`. This means
+ * you'll need to adjust accordingly when using these coordinates
+ * for drawing or other grid operations.
  */
 export interface MousePosition {
     /** Grid X coordinate (column), -1 if mouse is outside grid */

package/dist/types/textmode/managers/TouchManager.d.ts

@@ -26,6 +26,11 @@ export interface TouchPosition {
 }
 /**
  * Touch event data.
+ *
+ * Unlike the main drawing logic, where `(0,0,0)` is the center cell,
+ * the mouse coordinates use the top-left cell as `(0,0)`. This means
+ * you'll need to adjust accordingly when using these coordinates
+ * for drawing or other grid operations.
  */
 export interface TouchEventData {
     /** The touch point that triggered this event */

package/dist/types/textmode/mixins/interfaces/IKeyboardMixin.d.ts

@@ -70,7 +70,6 @@ export interface IKeyboardMixin {
     *
     *   // Show the last pressed key at the center of the grid
     *   t.push();
-    *   t.translate(t.grid.cols / 2, t.grid.rows / 2);
     *   t.char(lastKey.length ? lastKey[0] : '?');
     *   t.point();
     *   t.pop();

package/dist/types/textmode/mixins/interfaces/IRenderingMixin.d.ts

@@ -12,10 +12,13 @@ export interface IRenderingMixin {
      * @param shader The custom shader to use
      *
      * @example
-     * ```javascript
-     * const t = textmode.create({ width: 800, height: 600 });
-     *
-     * const glitchShader = t.createFilterShader(`#version 300 es
+    * ```javascript
+    * const t = textmode.create({ width: 800, height: 600 });
+    *
+    * let glitchShader;
+    *
+    * t.setup(async() => {
+    *     glitchShader = await t.createFilterShader(`#version 300 es
      *   precision highp float;
      *   in vec2 v_uv;
      *   uniform float u_intensity;
@@ -33,11 +36,11 @@ export interface IRenderingMixin {
      *   }
      * `);
      *
-     * t.draw(() => {
-     *   t.shader(glitchShader);
-     *   t.setUniform('u_intensity', Math.sin(t.frameCount * 0.1) * 0.02);
-     *   t.rect(t.grid.cols, t.grid.rows);
-     * });
+    * t.draw(() => {
+    *     t.shader(glitchShader);
+    *     t.setUniform('u_intensity', Math.sin(t.frameCount * 0.1) * 0.02);
+    *     t.rect(t.grid.cols, t.grid.rows);
+    * });
      * ```
      */
     shader(shader: GLShader): void;
@@ -196,7 +199,10 @@ export interface IRenderingMixin {
      * ```javascript
      * const t = textmode.create({ width: 800, height: 600 });
      *
-     * const pulseShader = t.createFilterShader(`#version 300 es
+     * let pulseShader;
+     *
+     * t.setup(async () => {
+     *     pulseShader = await t.createFilterShader(`#version 300 es
      *   precision highp float;
      *   in vec2 v_uv;
      *   uniform float u_time;
@@ -212,11 +218,12 @@ export interface IRenderingMixin {
      *     o_secondaryColor = vec4(color * 0.3, 1.0);
      *   }
      * `);
+     * });
      *
      * t.draw(() => {
-     *   t.shader(pulseShader);
-     *   t.setUniform('u_time', t.frameCount * 0.005);
-     *   t.rect(t.grid.cols, t.grid.rows);
+     *     t.shader(pulseShader);
+     *     t.setUniform('u_time', t.frameCount * 0.005);
+     *     t.rect(t.grid.cols, t.grid.rows);
      * });
      * ```
      */
@@ -229,7 +236,10 @@ export interface IRenderingMixin {
      * ```javascript
      * const t = textmode.create({ width: 800, height: 600 });
      *
-     * const rippleShader = t.createFilterShader(`#version 300 es
+     * let rippleShader;
+     *
+     * t.setup(async() => {
+     *     rippleShader = await t.createFilterShader(`#version 300 es
      *   precision highp float;
      *   in vec2 v_uv;
      *   uniform float u_time;
@@ -247,14 +257,15 @@ export interface IRenderingMixin {
      *     o_secondaryColor = vec4(color * 0.4, 1.0);
      *   }
      * `);
+     * });
      *
      * t.draw(() => {
-     *   t.shader(rippleShader);
-     *   t.setUniforms({
-     *     u_time: t.frameCount * 0.0005,
-     *     u_center: [0.5, 0.5]
-     *   });
-     *   t.rect(t.grid.cols, t.grid.rows);
+     *     t.shader(rippleShader);
+     *     t.setUniforms({
+     *         u_time: t.frameCount * 0.0005,
+     *         u_center: [0.5, 0.5]
+     *     });
+     *     t.rect(t.grid.cols, t.grid.rows);
      * });
      * ```
      */
@@ -310,6 +321,52 @@ export interface IRenderingMixin {
     * ```
      */
     createFilterShader(fragmentSource: string): Promise<GLShader>;
+    /**
+     * Create a custom shader from vertex and fragment shader source code or file paths.
+     * Both the vertex and fragment shaders can be provided as inline GLSL source code
+     * or as file paths (e.g., './vertex.vert', './fragment.frag').
+     * @param vertexSource The vertex shader source code or a file path (e.g., './shader.vert')
+     * @param fragmentSource The fragment shader source code or a file path (e.g., './shader.frag')
+     * @returns A Promise that resolves to a compiled shader ready for use with {@link shader}
+     *
+    * @example
+    * ```javascript
+    * const t = textmode.create({
+    *   width: 800,
+    *   height: 600,
+    * });
+    *
+    * let customShader;
+    *
+    * t.setup(async () => {
+    *   // Load shaders from files
+    *   customShader = await t.createShader('./vertex.vert', './fragment.frag');
+    *
+    *   // Or create from inline source
+    *   // customShader = await t.createShader(
+    *   //   `#version 300 es
+    *   //   in vec2 a_position;
+    *   //   void main() {
+    *   //     gl_Position = vec4(a_position, 0.0, 1.0);
+    *   //   }`,
+    *   //   `#version 300 es
+    *   //   precision highp float;
+    *   //   out vec4 fragColor;
+    *   //   void main() {
+    *   //     fragColor = vec4(1.0, 0.0, 0.0, 1.0);
+    *   //   }`
+    *   // );
+    * });
+    *
+    * t.draw(() => {
+    *   if (customShader) {
+    *     t.shader(customShader);
+    *     t.rect(t.grid.cols, t.grid.rows);
+    *   }
+    * });
+    * ```
+     */
+    createShader(vertexSource: string, fragmentSource: string): Promise<GLShader>;
     /**
      * Sets the rotation angles for subsequent shape rendering operations.
      *
@@ -837,18 +894,12 @@ export interface IRenderingMixin {
      *   height: 600,
      * })
      *
-     * let semicolon;
-     *
-     * t.setup(() => {
-     *  semicolon = t.color(';');
-     * });
-     *
      * t.draw(() => {
      *   t.background(0);
      *   t.char('A');
      *   t.rect(10, 10);
      *
-     *   t.char(semicolon);
+     *   t.char(";");
      *   t.translate(15, 0);
      *   t.rect(10, 10);
      * });
@@ -922,6 +973,7 @@ export interface IRenderingMixin {
      * t.draw(() => {
      *   t.background(0);
      *   t.flipX(true);
+     *   t.char('A');
      *   t.rect(5, 5);
      * });
      * ```
@@ -941,6 +993,7 @@ export interface IRenderingMixin {
      * t.draw(() => {
      *   t.background(0);
      *   t.flipY(true);
+     *   t.char('A');
      *   t.rect(5, 5);
      * });
      * ```

package/dist/types/textmode/mixins/interfaces/ITouchMixin.d.ts

@@ -177,7 +177,7 @@ export interface ITouchMixin {
      * ```javascript
      * t.draw(() => {
      *   for (const touch of t.touches) {
-     *     t.point(touch.x, touch.y);
+     *     t.point();
      *   }
      * });
      * ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "textmode.js",
-  "version": "0.6.1",
+  "version": "0.7.0-beta.2",
   "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",