textmode.js 0.1.9-beta.5 → 0.1.9

package/dist/types/rendering/core/Shader.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Core shader abstractions for textmode.js rendering system.
+ * Provides base classes and interfaces for WebGL and future WebGPU shader implementations.
+ */
+import type { IFramebuffer } from './Framebuffer';
+/**
+ * Supported uniform value types
+ */
+export type UniformValue = number | boolean | number[] | Float32Array | Int32Array | IFramebuffer;
+/**
+ * Core interface that all shader implementations must satisfy.
+ * Defines the contract for shader programs across different graphics APIs.
+ * @ignore
+ */
+export interface IShader {
+    /** Whether the shader is currently compiled and ready to use */
+    readonly isReady: boolean;
+    /**
+     * Activate this shader for rendering.
+     * Makes this shader the active program for subsequent draw calls.
+     * @ignore
+     */
+    $use(): void;
+    /**
+     * Set a uniform value by name.
+     * @param name Name of the uniform
+     * @param value Value to set
+     */
+    setUniform(name: string, value: UniformValue): void;
+    /**
+     * Set multiple uniforms at once.
+     * @param uniforms Object containing uniform name-value pairs
+     */
+    setUniforms(uniforms: Record<string, UniformValue>): void;
+    /**
+     * Reset internal state (texture units, etc.) for a new frame.
+     * @ignore
+     */
+    $resetState(): void;
+    /**
+     * Dispose of resources used by this shader.
+     * After calling this method, the shader should not be used.
+     * @ignore
+     */
+    $dispose(): void;
+}
+/**
+ * Abstract base class for shader implementations.
+ */
+export declare abstract class Shader implements IShader {
+    protected _isReady: boolean;
+    protected constructor();
+    get isReady(): boolean;
+    setUniforms(uniforms: Record<string, UniformValue>): void;
+    abstract $use(): void;
+    abstract setUniform(name: string, value: UniformValue): void;
+    abstract $resetState(): void;
+    abstract $dispose(): void;
+}

package/dist/types/rendering/core/index.d.ts

@@ -0,0 +1,2 @@
+export * from './Framebuffer';
+export * from './Shader';

package/dist/types/rendering/index.d.ts

@@ -1,3 +1,4 @@
-export { Shader } from './webgl/Shader';
+export * from './core';
+export { GLShader as Shader } from './webgl/Shader';
 export { GLRenderer } from './webgl/Renderer';
-export { Framebuffer } from './webgl/Framebuffer';
+export { GLFramebuffer } from './webgl/Framebuffer';

package/dist/types/rendering/webgl/Framebuffer.d.ts

@@ -1,26 +1,14 @@
-export interface FramebufferOptions {
-    filter?: 'nearest' | 'linear';
-    wrap?: 'clamp' | 'repeat';
-    format?: 'rgba' | 'rgb';
-    type?: 'unsigned_byte' | 'float';
-}
-/**
- * Supported media sources for framebuffer textures
- */
-export type MediaSource = HTMLCanvasElement | HTMLVideoElement;
+import { Framebuffer, type FramebufferOptions } from '../core/Framebuffer';
 /**
- * Wrapper for WebGL framebuffer with automatic texture creation.
+ * WebGL implementation of the framebuffer abstraction.
+ * Provides GPU-accelerated render targets with automatic texture creation.
  * Can also be used as a standalone texture (without render target functionality).
  */
-export declare class Framebuffer {
+export declare class GLFramebuffer extends Framebuffer {
     private _gl;
     private _framebuffer;
     private _texture;
-    private _width;
-    private _height;
-    private _options;
     private _previousState;
-    private _pixels;
     constructor(gl: WebGLRenderingContext, width: number, height?: number, options?: FramebufferOptions);
     /**
      * Execute a function with this framebuffer bound, then restore previous binding
@@ -32,7 +20,7 @@ export declare class Framebuffer {
     /**
      * Update the framebuffer texture with canvas or video content
      */
-    update(source: MediaSource): void;
+    $update(source: HTMLCanvasElement | HTMLVideoElement): void;
     /**
      * Update the framebuffer texture with pixel data
      */
@@ -78,7 +66,4 @@ export declare class Framebuffer {
     $dispose(): void;
     get framebuffer(): WebGLFramebuffer | null;
     get texture(): WebGLTexture;
-    get width(): number;
-    get height(): number;
-    get pixels(): Uint8Array | null;
 }

package/dist/types/rendering/webgl/Renderer.d.ts

@@ -1,5 +1,7 @@
-import { Framebuffer, type FramebufferOptions } from "./Framebuffer";
-import { Shader } from "./Shader";
+import { GLFramebuffer } from "./Framebuffer";
+import type { Framebuffer, FramebufferOptions } from '../core/Framebuffer';
+import { GLShader } from "./Shader";
+import type { UniformValue } from "../core";
 /**
  * Core WebGL renderer that manages the WebGL context and provides high-level rendering operations
  */
@@ -21,7 +23,7 @@ export declare class GLRenderer {
     /**
      * Set the current shader
      */
-    $shader(shader: Shader): void;
+    $shader(shader: GLShader): void;
     /**
      * Sets the fill color for subsequent rendering operations
      * @param r Red component *(0-255)*
@@ -76,12 +78,12 @@ export declare class GLRenderer {
      * @returns true if WebGL2, false if WebGL1
      */
     private _detectShaderVersion;
-    $createShader(vertexSource: string, fragmentSource: string): Shader;
-    $createFilterShader(fragmentSource: string): Shader;
+    $createShader(vertexSource: string, fragmentSource: string): GLShader;
+    $createFilterShader(fragmentSource: string): GLShader;
     /**
      * Set a uniform value for the current shader
      */
-    $setUniform(name: string, value: any): void;
+    $setUniform(name: string, value: UniformValue): void;
     /**
      * Draw a rectangle with the current fill and/or stroke settings
      */
@@ -102,7 +104,7 @@ export declare class GLRenderer {
     /**
      * Create a new framebuffer
      */
-    $createFramebuffer(width: number, height: number, options?: FramebufferOptions): Framebuffer;
+    $createFramebuffer(width: number, height: number, options?: FramebufferOptions): GLFramebuffer;
     /**
      * Fill the current framebuffer with a solid color
      */

package/dist/types/rendering/webgl/Shader.d.ts

@@ -1,14 +1,30 @@
+import { Shader, type UniformValue } from '../core/Shader';
 /**
- * Shader program wrapper with simplified uniform management
+ * WebGL implementation of the shader abstraction.
+ * Provides GPU shader program management with automatic uniform handling.
  */
-export declare class Shader {
+export declare class GLShader extends Shader {
     private _gl;
     private _program;
     private _uniformLocations;
     private _uniformTypes;
     private _textureUnitCounter;
     private _maxTextureUnits;
+    /**
+     * Creates a new GLShader instance.
+     * @param gl The WebGL rendering context.
+     * @param vertexSource The source code for the vertex shader.
+     * @param fragmentSource The source code for the fragment shader.
+     * @ignore
+     */
     constructor(gl: WebGLRenderingContext, vertexSource: string, fragmentSource: string);
+    /**
+     * Factory method to create a shader from source object
+     */
+    static fromSource(gl: WebGLRenderingContext, source: {
+        vertex: string;
+        fragment: string;
+    }): GLShader;
     private _cacheLocations;
     private _createProgram;
     private _createShader;
@@ -16,10 +32,14 @@ export declare class Shader {
      * Use this shader program
      */
     $use(): void;
+    /**
+     * Reset texture unit counter and other state
+     */
+    $resetState(): void;
     /**
      * Set a single uniform value with automatic texture unit management
      */
-    setUniform(name: string, value: any): void;
+    setUniform(name: string, value: UniformValue): void;
     private _getNextTextureUnit;
     /**
      * Check if a uniform is an integer type
@@ -34,8 +54,4 @@ export declare class Shader {
      * This method is idempotent and safe to call multiple times.
      */
     $dispose(): void;
-    /**
-     * Reset texture unit counter (useful when starting a new frame)
-     */
-    private _resetTextureUnits;
 }

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

@@ -1,4 +1,4 @@
-import type { Framebuffer } from "../rendering/webgl/Framebuffer";
+import type { Framebuffer } from "../rendering/core/Framebuffer";
 import type { GLRenderer } from "../rendering/webgl/Renderer";
 import { TextmodeBrightnessConverter, TextmodeConverter } from "./converters";
 import type { TextmodeFont } from "./font";

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

@@ -21,15 +21,15 @@ export type TextmodeOptions = {
     fontSize?: number;
     /**
      * Automatic rendering mode. Defaults to 'auto'.
-     * - 'manual': Requires manual `render()` calls
-     * - 'auto': Automatically renders using [requestAnimationFrame](https://developer.mozilla.org/en-US/docs/Web/API/window/requestAnimationFrame)
+     * - `'manual'`: Requires manual `render()` calls
+     * - `'auto'`: Automatically renders using [requestAnimationFrame](https://developer.mozilla.org/en-US/docs/Web/API/window/requestAnimationFrame)
      */
     renderMode?: 'manual' | 'auto';
     /** Maximum frames per second for auto rendering. Defaults to 60. */
     frameRate?: number;
-    /** The width of the canvas in standalone mode. Defaults to 800. */
+    /** The width of the canvas in `standalone` mode. Defaults to 800. */
     width?: number;
-    /** The height of the canvas in standalone mode. Defaults to 600. */
+    /** The height of the canvas in `standalone` mode. Defaults to 600. */
     height?: number;
     /**
      * URL or path to a custom font file *(.otf/.ttf)*.

package/dist/types/textmode/converters/BrightnessConverter.d.ts

@@ -1,36 +1,36 @@
 import { GLRenderer } from "../../rendering/webgl/Renderer";
-import { Framebuffer } from "../../rendering/webgl/Framebuffer";
 import { TextmodeFont } from "../font";
 import { TextmodeGrid } from "../Grid";
-import { TextmodeFeatureConverter } from "./FeatureConverter";
-export declare const BRIGHTNESS_DEFAULT_OPTIONS: {
-    /** Enable/disable the renderer */
-    enabled: boolean;
-    /** Characters used for brightness mapping (from darkest to brightest) */
-    characters: string;
-    /** Color of the ASCII characters. Only used when `characterColorMode` is set to `fixed` */
-    characterColor: number[];
-    /** Character color mode */
-    characterColorMode: string;
-    /** Cell background color. Only used when `characterColorMode` is set to `fixed` */
-    cellColor: number[];
-    /** Background color mode */
-    cellColorMode: string;
-    /** Swap the cells ASCII character colors with it's cell background colors */
-    invert: boolean;
-    /** Rotation angle of all characters in the grid in degrees */
-    rotation: number[];
-    /** Flip the ASCII characters horizontally */
-    flipHorizontally: boolean;
-    /** Flip the ASCII characters vertically */
-    flipVertically: boolean;
+import { TextmodeFeatureConverter, type TextmodeFeatureConverterOptions } from "./FeatureConverter";
+import type { Framebuffer } from "../../rendering";
+/**
+ * Options interface for the brightness converter.
+ */
+export interface TextmodeBrightnessConverterOptions extends TextmodeFeatureConverterOptions {
     /** Range of brightness values to map to ASCII characters */
     brightnessRange: [number, number];
-};
+}
+/**
+ * Default brightness converter options used when no options are specified.
+ *
+ * **Default values:**
+ * - `enabled`: `true` - Enable the brightness converter
+ * - `characters`: `" .:-=+*%@#"` - Character set for brightness mapping *(from darkest to brightest)*
+ * - `characterColor`: `#FFFFFF` - White color for ASCII characters *(only used when `characterColorMode` is `'fixed'`)*
+ * - `characterColorMode`: `'sampled'` - Sample character colors from source texture
+ * - `cellColor`: `#000000` - Black background color for cells *(only used when `cellColorMode` is `'fixed'`)*
+ * - `cellColorMode`: `'fixed'` - Use fixed background color for all cells
+ * - `invert`: `false` - Don't swap character and background colors
+ * - `rotation`: `0` - No rotation applied to characters
+ * - `flipHorizontally`: `false` - Don't flip characters horizontally
+ * - `flipVertically`: `false` - Don't flip characters vertically
+ * - `brightnessRange`: `[0, 255]` - Full brightness range for character mapping
+ */
+export declare const BRIGHTNESS_DEFAULT_OPTIONS: TextmodeBrightnessConverterOptions;
 /**
  * Converter that maps brightness values from a source texture to ASCII characters.
  */
-export declare class TextmodeBrightnessConverter extends TextmodeFeatureConverter {
+export declare class TextmodeBrightnessConverter extends TextmodeFeatureConverter<TextmodeBrightnessConverterOptions> {
     private _sampleShader;
     private _colorFillShader;
     private _charMappingShader;

package/dist/types/textmode/converters/Converter.d.ts

@@ -1,11 +1,18 @@
 import type { TextmodeFont } from "../font";
-import type { Framebuffer } from "../../rendering/webgl/Framebuffer";
 import type { GLRenderer } from "../../rendering/webgl/Renderer";
 import type { TextmodeGrid } from "../Grid";
+import type { Framebuffer } from "../../rendering";
+/**
+ * Base options interface for all textmode converters.
+ */
+export interface TextmodeConverterOptions {
+    /** Enable/disable the converter */
+    enabled: boolean;
+}
 /**
  * Base class for all textmode converters.
  */
-export declare class TextmodeConverter {
+export declare class TextmodeConverter<TOptions extends TextmodeConverterOptions = TextmodeConverterOptions> {
     protected _renderer: GLRenderer;
     protected _fontManager: TextmodeFont;
     protected _grid: TextmodeGrid;
@@ -14,7 +21,7 @@ export declare class TextmodeConverter {
     protected _secondaryColorFramebuffer: Framebuffer;
     protected _rotationFramebuffer: Framebuffer;
     protected _transformFramebuffer: Framebuffer;
-    protected _options: any;
+    protected _options: TOptions;
     /**
      * Creates a new TextmodeConverter instance.
      * @param renderer Renderer instance for texture creation
@@ -23,7 +30,7 @@ export declare class TextmodeConverter {
      * @param options Additional options for the converter
      * @ignore
      */
-    constructor(renderer: GLRenderer, fontManager: TextmodeFont, grid: TextmodeGrid, options?: any);
+    constructor(renderer: GLRenderer, fontManager: TextmodeFont, grid: TextmodeGrid, options?: Partial<TOptions>);
     /**
      * Resizes all internal framebuffers to match the grid dimensions.
      * @ignore
@@ -58,5 +65,5 @@ export declare class TextmodeConverter {
     /** Returns the framebuffer containing transformation data. */
     get transformFramebuffer(): Framebuffer;
     /** Returns the defined options for this converter. */
-    get options(): any;
+    get options(): TOptions;
 }

package/dist/types/textmode/converters/FeatureConverter.d.ts

@@ -2,14 +2,37 @@ import { TextmodeColorPalette } from "../../ColorPalette";
 import type { TextmodeFont } from "../font";
 import type { GLRenderer } from "../../rendering/webgl/Renderer";
 import type { TextmodeGrid } from "../Grid";
-import { TextmodeConverter } from "./Converter";
-import type { Framebuffer } from "../../rendering/webgl/Framebuffer";
+import { TextmodeConverter, type TextmodeConverterOptions } from "./Converter";
+import type { Framebuffer } from "../../rendering";
+/**
+ * Options interface for feature-based textmode converters.
+ */
+export interface TextmodeFeatureConverterOptions extends TextmodeConverterOptions {
+    /** Characters used for mapping, usually ordered from least dense to most dense */
+    characters: string;
+    /** Color of the characters. Only used when `characterColorMode` is set to `'fixed'` */
+    characterColor: [number, number, number, number];
+    /** Character color mode */
+    characterColorMode: "sampled" | "fixed";
+    /** Cell background color. Only used when `cellColorMode` is set to `'fixed'` */
+    cellColor: [number, number, number, number];
+    /** Background color mode */
+    cellColorMode: "sampled" | "fixed";
+    /** Swap the character and cell colors */
+    invert: boolean;
+    /** Rotation angle stored as RGBA where RGB encodes the rotation and A is always 1 */
+    rotation: [number, number, number, number];
+    /** Flip the characters horizontally */
+    flipHorizontally: boolean;
+    /** Flip the characters vertically */
+    flipVertically: boolean;
+}
 /**
  * Abstract base class for all feature-based textmode converters like `'brightness'`.
  */
-export declare abstract class TextmodeFeatureConverter extends TextmodeConverter {
+export declare abstract class TextmodeFeatureConverter<TOptions extends TextmodeFeatureConverterOptions = TextmodeFeatureConverterOptions> extends TextmodeConverter<TOptions> {
     protected _palette: TextmodeColorPalette;
-    protected constructor(renderer: GLRenderer, fontManager: TextmodeFont, grid: TextmodeGrid, options?: any);
+    protected constructor(renderer: GLRenderer, fontManager: TextmodeFont, grid: TextmodeGrid, options?: Partial<TOptions>);
     /**
      * Converts the source framebuffer to the target format.
      * @param sourceFramebuffer The source framebuffer to convert.
@@ -87,7 +110,6 @@ export declare abstract class TextmodeFeatureConverter extends TextmodeConverter
      * Helper method to set color mode with validation.
      * @param mode The color mode to set.
      * @param optionKey The option key to set in _options.
-     * @param errorMessage The error message to show if validation fails.
      */
     private _setColorMode;
     /**

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

@@ -1,3 +1,3 @@
-export { TextmodeConverter } from './Converter';
-export { TextmodeFeatureConverter } from './FeatureConverter';
-export { TextmodeBrightnessConverter } from './BrightnessConverter';
+export { TextmodeConverter, type TextmodeConverterOptions } from './Converter';
+export { TextmodeFeatureConverter, type TextmodeFeatureConverterOptions } from './FeatureConverter';
+export { TextmodeBrightnessConverter, type TextmodeBrightnessConverterOptions, BRIGHTNESS_DEFAULT_OPTIONS } from './BrightnessConverter';

package/dist/types/textmode/font/TextmodeFont.d.ts

@@ -1,5 +1,5 @@
 import type { GLRenderer } from '../../rendering/webgl/Renderer.ts';
-import type { Framebuffer } from '../../rendering/webgl/Framebuffer.ts';
+import type { GLFramebuffer } from '../../rendering/webgl/Framebuffer.ts';
 import type { TextmodeCharacter } from './types.ts';
 import type { TyprFont } from './typr/types.ts';
 /**
@@ -86,7 +86,7 @@ export declare class TextmodeFont {
      * Returns the WebGL framebuffer containing the font texture atlas.
      * @ignore
      */
-    get fontFramebuffer(): Framebuffer;
+    get fontFramebuffer(): GLFramebuffer;
     /** Returns the array of {@link TextmodeCharacter} objects in the font. */
     get characters(): TextmodeCharacter[];
     /** Returns the number of columns in the texture atlas. */

package/dist/types/textmode/font/TextureAtlas.d.ts

@@ -1,6 +1,6 @@
 import type { TextmodeCharacter, GlyphDimensions } from './types.ts';
 import type { GLRenderer } from '../../rendering/webgl/Renderer.ts';
-import type { Framebuffer } from '../../rendering/webgl/Framebuffer.ts';
+import type { GLFramebuffer } from '../../rendering/webgl/Framebuffer.ts';
 import type { TyprFont } from './typr/types.ts';
 /**
  * Handles creation of texture atlases for font rendering.
@@ -27,7 +27,7 @@ export declare class TextureAtlasCreation {
      * @returns Object containing framebuffer, columns, and rows
      */
     createTextureAtlas(characters: TextmodeCharacter[], maxGlyphDimensions: GlyphDimensions, fontSize: number, fontDataOrFamilyName: TyprFont | string): {
-        framebuffer: Framebuffer;
+        framebuffer: GLFramebuffer;
         columns: number;
         rows: number;
     };

package/dist/types/textmode/font/utils/FontTableReader.d.ts

@@ -1,4 +1,4 @@
-import type { TyprFont, CmapTable } from '../typr/types.ts';
+import type { TyprFont } from '../typr/types.ts';
 /**
  * Centralized font table reader that eliminates redundant font data access.
  * Provides cached access to font tables and metrics with consistent error handling.
@@ -6,14 +6,9 @@ import type { TyprFont, CmapTable } from '../typr/types.ts';
 export declare class FontTableReader {
     private _glyphIndexCache;
     private _cmapTableCache;
-    /**
-     * Gets the best character mapping table for Unicode text.
-     * Prefers format 4 (BMP Unicode) or format 12 (full Unicode).
-     * Results are cached per font.
-     */
-    $getBestCmapTable(font: TyprFont): CmapTable | null;
     /**
      * Gets the glyph index for a given Unicode code point.
+     * Searches through all available cmap tables to find the character.
      * Results are cached per font and character.
      */
     $getGlyphIndex(font: TyprFont, codePoint: number): number;

package/dist/types/textmode/mixins/RenderingMixin.d.ts

@@ -1,6 +1,6 @@
 import type { Mixin } from './TextmodifierMixin';
-import type { Framebuffer, Shader } from '../../rendering';
-import type { FramebufferOptions } from '../../rendering/webgl/Framebuffer';
+import type { Framebuffer, Shader, UniformValue } from '../../rendering';
+import type { FramebufferOptions } from '../../rendering/core/Framebuffer';
 /**
  * Interface for rendering capabilities that will be mixed into Textmodifier
  */
@@ -401,7 +401,7 @@ export interface RenderingCapabilities {
      * @param name The name of the uniform variable to set.
      * @param value The value to set for the uniform variable.
      */
-    setUniform(name: string, value: any): void;
+    setUniform(name: string, value: UniformValue): void;
     /**
      * Draw an image to the canvas.
      * @param source The image source

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "textmode.js",
-  "version": "0.1.9-beta.5",
+  "version": "0.1.9",
   "description": "Apply real-time ASCII conversion to any HTML canvas.",
   "type": "module",
   "types": "./dist/types/index.d.ts",

package/dist/types/rendering/core/AbstractFramebuffer.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/rendering/core/AbstractGeometry.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/rendering/core/AbstractShader.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/rendering/core/AbstractTexture.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/rendering/core/GraphicsContext.d.ts

@@ -1 +0,0 @@
-export {};