textmode.js 0.1.9 → 0.2.0-beta.1

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

@@ -0,0 +1,15 @@
+/**
+ * Minimal VAO manager that caches unit-geometry attribute setup per (program, geometry type).
+ * It binds only non-instanced attributes (a_position, a_texCoord). Instanced attributes are
+ * still configured by InstanceBatch per draw to keep buffers flexible.
+ */
+import type { UnitGeometryData } from './types/GeometryTypes';
+export declare class VAOManager {
+    private readonly _gl;
+    private readonly _cache;
+    constructor(gl: WebGL2RenderingContext);
+    /** Bind or create a VAO for the given program and geometry key. */
+    $bind(program: WebGLProgram, geometryKey: string, unit: UnitGeometryData, geometryBuffer: WebGLBuffer): void;
+    $unbind(): void;
+    $dispose(): void;
+}

package/dist/types/rendering/webgl/geometries/Arc.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Instanced arc (pie segment) geometry implementation
+ */
+import type { InstanceBatch } from '../InstanceBatch';
+import { type ArcParams } from '../types/GeometryTypes';
+import { BaseGeometry } from './BaseGeometry';
+/**
+ * Instanced arc geometry renderer.
+ * Batches arc draw calls using a unit triangle fan scaled to width/height.
+ * Angles are specified in DEGREES by the API, converted to radians here.
+ */
+export declare class Arc extends BaseGeometry {
+    constructor(gl: WebGL2RenderingContext, batch: InstanceBatch);
+    /** Add an arc instance (filled pie segment) */
+    $addInstance(params: ArcParams, renderState: any): number;
+}

package/dist/types/rendering/webgl/geometries/BaseGeometry.d.ts

@@ -1,40 +1,46 @@
 /**
- * Base class for WebGL geometry rendering with shared vertex buffer management
+ * Base class for instanced geometry implementations
  */
-export declare abstract class BaseGeometry {
-    protected _gl: WebGLRenderingContext;
-    protected _unitBuffer: WebGLBuffer | null;
-    protected _bytesPerVertex: number;
-    private _attribCache;
-    constructor(gl: WebGLRenderingContext);
-    /**
-     * Ensure the unit buffer is created and bound
-     */
-    protected _ensureUnitBuffer(): void;
-    /**
-     * Enable vertex attributes and return their locations
-     */
-    protected _enableAttribs(): {
-        positionLoc: number;
-        texLoc: number;
-    };
+import type { InstanceBatch } from '../InstanceBatch';
+import type { InstanceData } from '../InstanceData';
+import type { IGeometry, GeometryType, UnitGeometryData } from '../types/GeometryTypes';
+/**
+ * Abstract base class for all instanced geometries.
+ * Provides common functionality for instance data creation and batch management.
+ */
+export declare abstract class BaseGeometry implements IGeometry {
+    protected readonly _gl: WebGL2RenderingContext;
+    protected readonly _batch: InstanceBatch;
+    protected readonly _type: GeometryType;
+    protected readonly _unitGeometry: UnitGeometryData;
+    private _unitBuffer;
+    constructor(gl: WebGL2RenderingContext, batch: InstanceBatch, type: GeometryType, unitGeometry: UnitGeometryData);
+    get type(): GeometryType;
+    get unitGeometry(): UnitGeometryData;
+    get unitBuffer(): WebGLBuffer;
+    get batch(): InstanceBatch;
+    $clearInstances(): void;
+    $hasInstances(): boolean;
+    $dispose(): void;
+    abstract $addInstance(params: any, renderState: any): number;
     /**
-     * Disable vertex attributes
+     * Create base instance data from render state.
+     * This method handles the common instance data creation logic.
+     * Subclasses can override this to add geometry-specific data.
      */
-    protected _disableAttribs(positionLoc: number, texLoc: number): void;
+    protected _createBaseInstanceData(x: number, y: number, width: number, height: number, renderState: any): InstanceData;
     /**
-     * Convert screen coordinates to NDC (Normalized Device Coordinates)
+     * Convert screen coordinates to NDC for compatibility with existing code
      */
     protected _toNDC(x: number, y: number): {
         nx: number;
         ny: number;
     };
-    /**
-     * Upload quad vertices to the buffer in NDC coordinates
-     */
-    protected _uploadQuadNDC(x1: number, y1: number, x2: number, y2: number): void;
-    /**
-     * Dispose of WebGL resources used by this geometry
-     */
-    $dispose(): void;
+    protected _setRotationCenter(instanceData: InstanceData, centerX: number, centerY: number): void;
+    protected _calculateRotationParams(x: number, y: number, width: number, height: number, rotationDegrees: number): {
+        centerX: number;
+        centerY: number;
+        radians: number;
+        aspectRatio: number;
+    };
 }

package/dist/types/rendering/webgl/geometries/BezierCurve.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Instanced bezier curve geometry implementation
+ */
+import type { InstanceBatch } from '../InstanceBatch';
+import { type BezierCurveParams } from '../types/GeometryTypes';
+import { BaseGeometry } from './BaseGeometry';
+/**
+ * TRUE INSTANCED bezier curve geometry renderer.
+ *
+ * APPROACH: Use a fixed multi-segment unit geometry shared by all curves.
+ * Each instance provides Bezier control points via instance attributes, and the
+ * vertex shader evaluates the curve mathematically to transform each segment.
+ *
+ * This maintains true instanced rendering: one draw call for all curves.
+ */
+export declare class BezierCurve extends BaseGeometry {
+    constructor(gl: WebGL2RenderingContext, batch: InstanceBatch);
+    /**
+     * Add a bezier curve instance to the batch - TRUE INSTANCED APPROACH
+     */
+    $addInstance(params: BezierCurveParams, renderState: any): number;
+}

package/dist/types/rendering/webgl/geometries/Ellipse.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Instanced ellipse geometry implementation
+ */
+import type { InstanceBatch } from '../InstanceBatch';
+import { type EllipseParams } from '../types/GeometryTypes';
+import { BaseGeometry } from './BaseGeometry';
+/**
+ * Instanced ellipse geometry renderer.
+ * Batches all ellipse draw calls for efficient GPU rendering.
+ */
+export declare class Ellipse extends BaseGeometry {
+    constructor(gl: WebGL2RenderingContext, batch: InstanceBatch);
+    /**
+     * Add an ellipse instance to the batch
+     * @param params Ellipse parameters (x,y as top-left corner, width/height as dimensions)
+     * @param renderState Current render state
+     * @returns Index of the added instance
+     */
+    $addInstance(params: EllipseParams, renderState: any): number;
+}

package/dist/types/rendering/webgl/geometries/Line.d.ts

@@ -1,11 +1,20 @@
+/**
+ * Instanced line geometry implementation
+ */
+import type { InstanceBatch } from '../InstanceBatch';
+import { type LineParams } from '../types/GeometryTypes';
 import { BaseGeometry } from './BaseGeometry';
 /**
- * Line geometry renderer
+ * Instanced line geometry renderer.
+ * Batches all line draw calls for efficient GPU rendering.
  */
 export declare class Line extends BaseGeometry {
-    constructor(gl: WebGLRenderingContext);
+    constructor(gl: WebGL2RenderingContext, batch: InstanceBatch);
     /**
-     * Draw a line from (x1, y1) to (x2, y2) with specified weight
+     * Add a line instance to the batch
+     * @param params Line parameters
+     * @param renderState Current render state
+     * @returns Index of the added instance
      */
-    $draw(x1: number, y1: number, x2: number, y2: number, weight: number): void;
+    $addInstance(params: LineParams, renderState: any): number;
 }

package/dist/types/rendering/webgl/geometries/Rectangle.d.ts

@@ -1,15 +1,20 @@
+/**
+ * Instanced rectangle geometry implementation
+ */
+import type { InstanceBatch } from '../InstanceBatch';
+import { type RectangleParams } from '../types/GeometryTypes';
 import { BaseGeometry } from './BaseGeometry';
 /**
- * Rectangle geometry renderer with fill and stroke support
+ * Instanced rectangle geometry renderer.
+ * Batches all rectangle draw calls for efficient GPU rendering.
  */
 export declare class Rectangle extends BaseGeometry {
-    constructor(gl: WebGLRenderingContext);
-    /**
-     * Draw a filled rectangle
-     */
-    $drawFill(x: number, y: number, width: number, height: number): void;
+    constructor(gl: WebGL2RenderingContext, batch: InstanceBatch);
     /**
-     * Draw a rectangle stroke (outline)
+     * Add a rectangle instance to the batch
+     * @param params Rectangle parameters
+     * @param renderState Current render state
+     * @returns Index of the added instance
      */
-    $drawStroke(x: number, y: number, width: number, height: number, weight: number): void;
+    $addInstance(params: RectangleParams, renderState: any): number;
 }

package/dist/types/rendering/webgl/geometries/Triangle.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Instanced triangle geometry implementation
+ */
+import type { InstanceBatch } from '../InstanceBatch';
+import { type TriangleParams } from '../types/GeometryTypes';
+import { BaseGeometry } from './BaseGeometry';
+/**
+ * Instanced triangle geometry renderer.
+ * Batches all triangle draw calls for efficient GPU rendering.
+ */
+export declare class Triangle extends BaseGeometry {
+    constructor(gl: WebGL2RenderingContext, batch: InstanceBatch);
+    /**
+     * Add a triangle instance to the batch
+     * @param params Triangle parameters
+     * @param renderState Current render state
+     * @returns Index of the added instance
+     */
+    $addInstance(params: TriangleParams, renderState: any): number;
+}

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

@@ -1,3 +1,6 @@
-export { BaseGeometry } from './BaseGeometry';
 export { Rectangle } from './Rectangle';
 export { Line } from './Line';
+export { Ellipse } from './Ellipse';
+export { Arc } from './Arc';
+export { Triangle } from './Triangle';
+export { BezierCurve } from './BezierCurve';

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

@@ -1 +1,17 @@
-export {};
+export * from './Framebuffer';
+export * from './Renderer';
+export * from './Shader';
+export * from './StateCache';
+export { GeometryType } from './types/GeometryTypes';
+export type { IGeometry as IInstancedGeometry, UnitGeometryData, RectangleParams, LineParams, EllipseParams, ArcParams, TriangleParams, BezierCurveParams, GeometryParams } from './types/GeometryTypes';
+export type { RenderContext, } from './types/RenderTypes';
+export type { InstanceData } from './InstanceData';
+export { PackedInstanceData, InstanceAttributeLayout } from './InstanceData';
+export { InstanceBatch } from './InstanceBatch';
+export { BaseGeometry } from './geometries/BaseGeometry';
+export { Rectangle } from './geometries/Rectangle';
+export { Line } from './geometries/Line';
+export { Ellipse } from './geometries/Ellipse';
+export { Arc } from './geometries/Arc';
+export { Triangle } from './geometries/Triangle';
+export { BezierCurve } from './geometries/BezierCurve';

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

@@ -0,0 +1,9 @@
+import type { GeometryParams, GeometryType } from './GeometryTypes';
+import type { IRenderState } from '../RenderState';
+export type DrawParams = GeometryParams;
+export interface DrawCommand {
+    id: number;
+    type: GeometryType;
+    params: DrawParams;
+    state: IRenderState;
+}

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

@@ -0,0 +1,144 @@
+/**
+ * Core interfaces and types for the instanced geometry system
+ */
+import type { InstanceBatch } from '../InstanceBatch';
+/**
+ * Geometry types supported by the instanced rendering system
+ */
+export declare enum GeometryType {
+    RECTANGLE = "rectangle",
+    LINE = "line",
+    ELLIPSE = "ellipse",
+    ARC = "arc",
+    TRIANGLE = "triangle",
+    BEZIER_CURVE = "bezier_curve",
+    CUSTOM = "custom"
+}
+/**
+ * Unit geometry vertex data for a specific geometry type
+ */
+export interface UnitGeometryData {
+    /** Vertex data as Float32Array (position + texCoord interleaved) */
+    vertices: Float32Array;
+    /** Number of vertices in the geometry */
+    vertexCount: number;
+    /** WebGL primitive type (gl.TRIANGLES, gl.LINES, etc.) */
+    primitiveType: number;
+    /** Stride in bytes between vertices */
+    stride: number;
+    /** Attribute configuration for position and texCoord */
+    attributes: {
+        position: {
+            size: number;
+            offset: number;
+        };
+        texCoord: {
+            size: number;
+            offset: number;
+        };
+    };
+}
+/**
+ * Interface for instanced geometry implementations
+ */
+export interface IGeometry {
+    /** The geometry type identifier */
+    readonly type: GeometryType;
+    /** The unit geometry data for this geometry type */
+    readonly unitGeometry: UnitGeometryData;
+    /** The instance batch for managing instances of this geometry */
+    readonly batch: InstanceBatch;
+    /**
+     * Add a new instance of this geometry to the batch
+     * @param params Geometry-specific parameters
+     * @param renderState Current render state
+     * @returns Index of the added instance
+     */
+    $addInstance(params: any, renderState: any): number;
+    /**
+     * Clear all instances from the batch
+     */
+    $clearInstances(): void;
+    /**
+     * Check if the geometry has any instances to render
+     */
+    $hasInstances(): boolean;
+    /**
+     * Dispose of geometry resources
+     */
+    $dispose(): void;
+}
+/**
+ * Parameters for rectangle geometry
+ */
+export interface RectangleParams {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Parameters for line geometry
+ */
+export interface LineParams {
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    thickness?: number;
+}
+/**
+ * Parameters for ellipse geometry
+ */
+export interface EllipseParams {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    startAngle?: number;
+    endAngle?: number;
+    segments?: number;
+}
+/**
+ * Parameters for arc geometry (filled pie segment)
+ * Angles are specified in DEGREES and arcs are drawn clockwise from start to stop.
+ * x, y specify the center of the arc (consistent with current ellipse implementation).
+ */
+export interface ArcParams {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    start: number;
+    stop: number;
+}
+/**
+ * Parameters for triangle geometry
+ */
+export interface TriangleParams {
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    x3: number;
+    y3: number;
+}
+/**
+ * Parameters for bezier curve geometry
+ */
+export interface BezierCurveParams {
+    x1: number;
+    y1: number;
+    cp1x: number;
+    cp1y: number;
+    cp2x: number;
+    cp2y: number;
+    x2: number;
+    y2: number;
+    thickness?: number;
+    segments?: number;
+}
+/**
+ * Union type for all geometry parameters
+ */
+export type GeometryParams = RectangleParams | LineParams | EllipseParams | ArcParams | TriangleParams | BezierCurveParams;

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

@@ -0,0 +1,12 @@
+/**
+ * Rendering pipeline interfaces and types
+ */
+import type { GLShader } from '../Shader';
+/**
+ * Render context containing shader and rendering configuration
+ */
+export interface RenderContext {
+    shader: GLShader;
+    gl: WebGL2RenderingContext;
+    viewport: [number, number, number, number];
+}

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

@@ -0,0 +1,81 @@
+/**
+ * Manages animation loop timing and frame rate control for textmode rendering.
+ * Provides precise frame rate limiting and smooth animation timing.
+ */
+export declare class AnimationController {
+    private _frameRateLimit;
+    private _frameInterval;
+    private _animationFrameId;
+    private _lastFrameTime;
+    private _isLooping;
+    private _frameRate;
+    private _lastRenderTime;
+    private _frameTimeHistory;
+    private _frameTimeHistorySize;
+    private _frameCount;
+    /**
+     * Creates an AnimationController instance.
+     * @param frameRateLimit Maximum frames per second. Defaults to 60.
+     */
+    constructor(frameRateLimit?: number);
+    /**
+     * Start the animation loop with the provided render callback.
+     * @param renderCallback Function to call for each frame render
+     */
+    start(renderCallback: () => void): void;
+    /**
+     * Stop the animation loop.
+     */
+    stop(): void;
+    /**
+     * Pause the animation loop without stopping it completely.
+     */
+    pause(): void;
+    /**
+     * Resume the animation loop if it was paused.
+     * @param renderCallback Function to call for each frame render
+     */
+    resume(renderCallback: () => void): void;
+    /**
+     * Set or get the frame rate limit.
+     * @param fps Optional new frame rate limit. If not provided, returns current measured frame rate.
+     * @param renderCallback Required when setting new frame rate and animation is running
+     * @returns Current measured frame rate when getting, void when setting
+     */
+    frameRate(fps?: number, renderCallback?: () => void): number | void;
+    /**
+     * Update frame rate measurement. Should be called on each render.
+     * Uses a rolling average for smoother frame rate reporting.
+     */
+    measureFrameRate(): void;
+    /**
+     * Check if the animation loop is currently active.
+     */
+    get isLooping(): boolean;
+    /**
+     * Get the current frame rate limit.
+     */
+    get frameRateLimit(): number;
+    /**
+     * Get the current measured frame rate.
+     */
+    get currentFrameRate(): number;
+    /**
+     * Get the current frame count.
+     */
+    get frameCount(): number;
+    /**
+     * Set the current frame count.
+     */
+    set frameCount(value: number);
+    /**
+     * Increment the frame count by one.
+     * Should be called on each render to track total frames rendered.
+     */
+    incrementFrame(): void;
+    /**
+     * Reset the frame count to zero.
+     * Useful when restarting animations or resetting state.
+     */
+    resetFrameCount(): void;
+}

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

@@ -1,37 +1,36 @@
 import type { TextmodeOptions } from "./Textmodifier";
 /**
- * Supported capture sources for textmode rendering.
- */
-export type TextmodeCaptureSource = HTMLCanvasElement | HTMLVideoElement;
-/**
- * TextmodeCanvas is a utility class that creates an overlay canvas
- * for rendering textmode graphics on top of an existing HTML canvas or video element,
- * or manages a standalone canvas for independent rendering.
+ * Manages a `HTMLCanvasElement` for textmode rendering.
  * @ignore
  */
 export declare class TextmodeCanvas {
     private _canvas;
-    private _captureSource;
-    private _isStandalone;
     private _resizeObserver?;
-    onTransformChange?: () => void;
-    constructor(captureSource: TextmodeCaptureSource, isStandalone?: boolean, opts?: TextmodeOptions);
+    private _canvasCreatedByUs;
+    /**
+     * Creates a new TextmodeCanvas instance.
+     * @param opts Options for creating or using an existing canvas
+     * @ignore
+     */
+    constructor(opts?: TextmodeOptions);
     private _createCanvas;
-    private _positionOverlayCanvas;
-    $resize(width?: number, height?: number): void;
     /**
-     * Get the WebGL context for the overlay canvas
+     * Resize the canvas to the specified width and height.
+     * If width or height is not provided, it retains the current dimension.
+     * @param width The new width of the canvas in pixels.
+     * @param height The new height of the canvas in pixels.
+     * @ignore
      */
-    $getWebGLContext(): WebGL2RenderingContext | WebGLRenderingContext;
+    $resize(width?: number, height?: number): void;
     /**
-     * Set up ResizeObserver to monitor for CSS transform changes
-     *
-     * note: might be redundant and can be deleted?
+     * Get the WebGL context for the overlay canvas
+     * @ignore
      */
-    private setupTransformObserver;
+    $getWebGLContext(): WebGL2RenderingContext;
     /**
      * Dispose of this TextmodeCanvas and clean up all resources.
      * This method is idempotent and safe to call multiple times.
+     * @ignore
      */
     $dispose(): void;
     get canvas(): HTMLCanvasElement;

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

@@ -1,5 +1,5 @@
 /**
- * Manages the grid for the ASCII rendering pipeline of a {@link Textmodifier} instance.
+ * Manages the grid of a {@link Textmodifier} instance.
  */
 export declare class TextmodeGrid {
     /** The number of columns in the grid. */
@@ -14,8 +14,6 @@ export declare class TextmodeGrid {
     private _offsetX;
     /** The offset to the outer canvas on the y-axis when centering the grid. */
     private _offsetY;
-    /** Whether the grid dimensions are fixed, or responsive based on the canvas dimensions. */
-    private _fixedDimensions;
     /** The canvas element used to determine the grid dimensions. */
     private _canvas;
     /** The width of each cell in the grid. */
@@ -35,10 +33,6 @@ export declare class TextmodeGrid {
      * @ignore
      */
     $reset(): void;
-    /**
-     * Reset the total grid width & height, and the offset to the outer canvas.
-     */
-    private _updateDimensions;
     /**
      * Re-assign the grid cell dimensions and `reset()` the grid.
      * @param newCellWidth The new cell width.
@@ -46,33 +40,6 @@ export declare class TextmodeGrid {
      * @ignore
      */
     $resizeCellPixelDimensions(newCellWidth: number, newCellHeight: number): void;
-    /**
-     * Re-assign the grid dimensions and resize the grid.
-     *
-     * Calling this method makes the grid dimensions fixed, meaning they will not automatically resize based on the canvas dimensions.
-     * @param newCols The new number of columns.
-     * @param newRows The new number of rows.
-     * @ignore
-     */
-    $resizeGridDimensions(newCols: number, newRows: number): void;
-    /**
-     * Make the grid dimensions flexible again, and `reset()` the grid.
-     * @ignore
-     */
-    $resetGridDimensions(): void;
-    /**
-     * Update the canvas used by the grid, and reset the grid dimensions.
-     * @param canvas The new canvas element to use for the grid.
-     * @ignore
-     */
-    $resize(): void;
-    /**
-     * Gets or sets whether the grid dimensions *(columns and rows)* are fixed or responsive based on the canvas dimensions.
-     * @param value Optional. `true` to make the grid dimensions fixed, or `false` to make them responsive. If not provided, returns the current state.
-     * @returns If no parameter is provided, returns `true` if the grid dimensions are fixed, or `false` if they are responsive.
-     * @ignore
-     */
-    $fixedDimensions(value?: boolean): boolean | void;
     /** Returns the width of each cell in the grid. */
     get cellWidth(): number;
     /** Returns the height of each cell in the grid. */