textmode.js 0.9.0 → 0.9.1

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

@@ -0,0 +1,132 @@
+import type { GLRenderer, GLShader, GLFramebuffer, UniformValue } from '../../rendering';
+import type { QueuedFilter, FilterName } from './types';
+/**
+ * Manages filter registration, shader compilation, and filter chain application.
+ *
+ * Used both for layer-level filters and global post-processing filters.
+ *
+ * @example
+ * ```ts
+ * // Register a custom filter
+ * await t.filters.register('brightness', brightnessShader, {
+ *     u_amount: ['amount', 1.0]
+ * });
+ *
+ * // Use the filter globally
+ * t.filter('brightness', 1.5);
+ *
+ * // Or on a layer
+ * t.layers.base.filter('brightness', { amount: 0.8 });
+ * ```
+ */
+export declare class TextmodeFilterManager {
+    private readonly _renderer;
+    private readonly _filters;
+    private readonly _shaderCache;
+    private readonly _copyShader;
+    private _pingPongBuffers;
+    private _isInitialized;
+    /**
+     * Create a new TextmodeFilterManager.
+     * @param renderer The WebGL renderer instance
+     * @ignore
+     */
+    constructor(renderer: GLRenderer);
+    /**
+     * Register a custom filter with the given ID, shader, and uniform definitions.
+     *
+     * @param id Unique filter identifier
+     * @param shader Pre-compiled GLShader, fragment shader source string, or path to a .frag/.glsl file
+     * @param uniformDefs Maps uniform names to [paramName, defaultValue] tuples
+     *
+     * @example
+     * ```ts
+     * // Register with inline shader source
+     * await t.filters.register('blur', blurFragSource, {
+     *     u_radius: ['radius', 5.0],
+     *     u_direction: ['direction', [1.0, 0.0]]
+     * });
+     *
+     * // Register with file path
+     * await t.filters.register('vignette', './vignette.frag', {
+     *     u_intensity: ['intensity', 0.5]
+     * });
+     * ```
+     */
+    register(id: FilterName, shader: GLShader | string, uniformDefs?: Record<string, [paramName: string, defaultValue: UniformValue]>): Promise<void>;
+    /**
+     * Unregister a filter by its ID.
+     *
+     * @param id The filter ID to unregister
+     * @returns true if the filter was unregistered, false if it wasn't found
+     */
+    unregister(id: FilterName): boolean;
+    /**
+     * Check if a filter with the given ID is registered.
+     *
+     * @param id The filter ID to check
+     * @returns true if the filter exists
+     */
+    has(id: FilterName): boolean;
+    /**
+     * Initialize ping-pong buffers for filter chain processing.
+     * @param width Buffer width in pixels
+     * @param height Buffer height in pixels
+     * @ignore
+     */
+    $initialize(width: number, height: number): void;
+    /**
+     * Apply a chain of filters to the source texture, outputting to target.
+     * Uses the manager's internal ping-pong buffers.
+     *
+     * @param sourceTexture The input texture
+     * @param targetFramebuffer The output framebuffer
+     * @param filters The queue of filters to apply in order
+     * @param width Framebuffer width
+     * @param height Framebuffer height
+     * @ignore
+     */
+    $applyFilters(sourceTexture: WebGLTexture, targetFramebuffer: GLFramebuffer, filters: QueuedFilter[], width: number, height: number): void;
+    /**
+     * Apply a chain of filters using external ping-pong buffers.
+     * This allows sharing the filter registry while using different buffer sizes
+     * (e.g., layer filters at grid dimensions vs global filters at canvas dimensions).
+     *
+     * @param sourceTexture The input texture
+     * @param targetFramebuffer The output framebuffer
+     * @param filters The queue of filters to apply in order
+     * @param width Framebuffer width
+     * @param height Framebuffer height
+     * @param pingPongBuffers External ping-pong buffers to use
+     * @ignore
+     */
+    $applyFiltersWithBuffers(sourceTexture: WebGLTexture, targetFramebuffer: GLFramebuffer, filters: QueuedFilter[], width: number, height: number, pingPongBuffers: [GLFramebuffer, GLFramebuffer]): void;
+    /**
+     * Apply a single filter pass with explicit source buffer.
+     */
+    private _applyFilterWithBuffer;
+    /**
+     * Get or create a cached shader for the given filter.
+     */
+    private _getOrCreateShader;
+    /**
+     * Copy a texture to a framebuffer using the copy shader.
+     */
+    private _copyTexture;
+    /**
+     * Resize the ping-pong buffers.
+     * @param width New width in pixels
+     * @param height New height in pixels
+     * @ignore
+     */
+    $resize(width: number, height: number): void;
+    /**
+     * Dispose of all resources.
+     * @ignore
+     */
+    $dispose(): void;
+    /**
+     * Register all built-in filters.
+     */
+    private _registerBuiltInFilters;
+}

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

@@ -0,0 +1,2 @@
+export type { FilterName, BuiltInFilterName, BuiltInFilterParams, QueuedFilter, FilterContext, TextmodeFilterStrategy, } from './types';
+export { TextmodeFilterManager } from './FilterManager';

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

@@ -0,0 +1,78 @@
+import type { GLShader } from '../../rendering';
+import type { UniformValue } from '../../rendering/webgl/types/UniformTypes';
+import type { GLRenderer } from '../../rendering/webgl/core/Renderer';
+/**
+ * Built-in filter names provided by textmode.js
+ */
+export type BuiltInFilterName = 'invert' | 'grayscale' | 'sepia' | 'threshold';
+/**
+ * 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;
+    /** Black/white threshold. Threshold: 0-1, default 0.5 */
+    threshold: number | {
+        threshold?: number;
+    };
+}
+/**
+ * A queued filter operation to be applied during rendering
+ * @ignore
+ */
+export interface QueuedFilter<TParams = unknown> {
+    name: FilterName;
+    params: TParams;
+}
+/**
+ * Context provided to filter strategies for shader creation
+ * @ignore
+ */
+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.
+ * @ignore
+ */
+export interface TextmodeFilterStrategy<TParams = unknown> {
+    /** 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: TParams, context: FilterContext): Record<string, UniformValue>;
+}

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

@@ -0,0 +1,14 @@
+/**
+ * Interface for objects that require explicit resource disposal.
+ */
+export interface IDisposable {
+    /**
+     * Dispose of the resource and free associated WebGL resources.
+     */
+    dispose(): void;
+    /**
+     * Register a callback to be run when this resource is disposed.
+     * @ignore
+     */
+    $addOnDispose?(callback: () => void): void;
+}