textmode.js 0.9.0 → 0.9.1

package/dist/types/rendering/webgl/core/interfaces/IRenderer.d.ts

@@ -0,0 +1,214 @@
+import type { GLFramebuffer, FramebufferOptions } from '../Framebuffer';
+import type { GLShader } from '../Shader';
+import type { UniformValue } from '../../types/UniformTypes';
+import type { RenderState } from '../../state/RenderState';
+/**
+ * Interface for the core WebGL renderer that manages the WebGL context and provides high-level rendering operations.
+ *
+ * This interface defines the contract for all rendering operations including:
+ * - Shader management and creation
+ * - Framebuffer operations
+ * - Primitive rendering (rectangles, lines, ellipses, triangles, arcs, bezier curves)
+ * - Image and texture rendering
+ * - State management
+ * - Viewport and clearing operations
+ */
+export interface IRenderer {
+    /**
+     * Get the WebGL rendering context.
+     * Provides direct access to the underlying WebGL2 context for advanced operations.
+     */
+    readonly context: WebGL2RenderingContext;
+    /**
+     * Get the current render state.
+     * The render state tracks the current rendering configuration including blend modes,
+     * colors, and other state that affects how primitives are drawn.
+     */
+    readonly state: RenderState;
+    /**
+     * Set the current shader for subsequent rendering operations.
+     * This binds the shader program and makes it active for all following draw calls
+     * until a different shader is set.
+     *
+     * @param shader - The shader to activate
+     */
+    $shader(shader: GLShader): void;
+    /**
+     * Create a new shader from vertex and fragment source code.
+     * The shader is compiled, linked, and cached by the shader manager.
+     *
+     * @param vertexSource - GLSL source code for the vertex shader
+     * @param fragmentSource - GLSL source code for the fragment shader
+     * @returns A compiled and linked shader program
+     */
+    $createShader(vertexSource: string, fragmentSource: string): GLShader;
+    /**
+     * Set a custom user shader for subsequent rendering operations.
+     * This shader will be used for primitive rendering instead of the default shader.
+     * The shader persists until explicitly reset via $resetShader() or by passing null.
+     *
+     * @param shader - The custom shader to use, or null to reset to default
+     */
+    $setUserShader(shader: GLShader | null): void;
+    /**
+     * Reset the current user shader to the default solid color shader.
+     * This clears both the active shader and any accumulated uniforms.
+     * Equivalent to calling $setUserShader(null).
+     */
+    $resetShader(): void;
+    /**
+     * Set a uniform value for the current user shader.
+     * The uniform must exist in the shader for this to have any effect.
+     *
+     * @param name - The name of the uniform variable in the shader
+     * @param value - The value to set (type must match the uniform type in the shader)
+     */
+    $setUniform(name: string, value: UniformValue): void;
+    /**
+     * Set multiple uniform values for the current user shader.
+     * This is a convenience method for setting multiple uniforms at once.
+     *
+     * @param uniforms - A record mapping uniform names to their values
+     */
+    $setUniforms(uniforms: Record<string, UniformValue>): void;
+    /**
+     * Create a filter shader using the standard instanced vertex shader.
+     * Filter shaders are commonly used for post-processing effects and only require
+     * a custom fragment shader since they use a standard quad-rendering vertex shader.
+     *
+     * @param fragmentSource - GLSL source code for the fragment shader
+     * @returns A shader configured for filter operations
+     */
+    $createFilterShader(fragmentSource: string): GLShader;
+    /**
+     * Draw a quad covering the pixel rectangle (x, y, width, height) on the canvas.
+     * The quad is converted to NDC (Normalized Device Coordinates) and rendered with the
+     * current shader using only the a_position attribute.
+     * Origin: top-left (canvas space).
+     *
+     * @param x - X coordinate of the top-left corner in pixels
+     * @param y - Y coordinate of the top-left corner in pixels
+     * @param width - Width of the quad in pixels
+     * @param height - Height of the quad in pixels
+     */
+    $quad(x: number, y: number, width: number, height: number): void;
+    /**
+     * Draw a rectangle.
+     * The rectangle is rendered using the current shader and render state.
+     * Positioning is controlled via the render state transform stack.
+     *
+     * @param width - Width of the rectangle
+     * @param height - Height of the rectangle
+     */
+    $rect(width: number, height: number): void;
+    /**
+     * Draw a line from one point to another.
+     * The line is rendered with the current stroke settings from the render state.
+     *
+     * @param x1 - X coordinate of the line start point
+     * @param y1 - Y coordinate of the line start point
+     * @param x2 - X coordinate of the line end point
+     * @param y2 - Y coordinate of the line end point
+     */
+    $line(x1: number, y1: number, x2: number, y2: number): void;
+    /**
+     * Draw an ellipse.
+     * The ellipse is centered at (0, 0) in the current local coordinate system.
+     * Positioning is controlled via the render state transform stack.
+     *
+     * @param width - Width of the ellipse
+     * @param height - Height of the ellipse
+     */
+    $ellipse(width: number, height: number): void;
+    /**
+     * Draw a triangle.
+     * The triangle is defined by three vertices and rendered with the current render state.
+     *
+     * @param x1 - First vertex X coordinate
+     * @param y1 - First vertex Y coordinate
+     * @param x2 - Second vertex X coordinate
+     * @param y2 - Second vertex Y coordinate
+     * @param x3 - Third vertex X coordinate
+     * @param y3 - Third vertex Y coordinate
+     */
+    $triangle(x1: number, y1: number, x2: number, y2: number, x3: number, y3: number): void;
+    /**
+     * Draw a cubic Bezier curve.
+     * The curve is defined by a start point, two control points, and an end point.
+     *
+     * @param x1 - Start point X coordinate
+     * @param y1 - Start point Y coordinate
+     * @param cp1x - First control point X coordinate
+     * @param cp1y - First control point Y coordinate
+     * @param cp2x - Second control point X coordinate
+     * @param cp2y - Second control point Y coordinate
+     * @param x2 - End point X coordinate
+     * @param y2 - End point Y coordinate
+     */
+    $bezierCurve(x1: number, y1: number, cp1x: number, cp1y: number, cp2x: number, cp2y: number, x2: number, y2: number): void;
+    /**
+     * Draw an arc (a portion of an ellipse).
+     * The arc is part of an ellipse centered at (0, 0) in the current local coordinate system,
+     * drawn from the start angle to the stop angle.
+     * Positioning is controlled via the render state transform stack.
+     *
+     * @param width - Width of the ellipse
+     * @param height - Height of the ellipse
+     * @param start - Start angle in radians
+     * @param stop - Stop angle in radians
+     */
+    $arc(width: number, height: number, start: number, stop: number): void;
+    /**
+     * Create a new framebuffer for off-screen rendering.
+     * Framebuffers can be used for render-to-texture operations, post-processing,
+     * and other advanced rendering techniques.
+     *
+     * @param width - Width of the framebuffer in pixels
+     * @param height - Height of the framebuffer in pixels
+     * @param attachmentCount - Number of color attachments (default: 1, supports MRT)
+     * @param options - Additional framebuffer configuration options
+     * @returns A new framebuffer instance
+     */
+    $createFramebuffer(width: number, height: number, attachmentCount?: number, options?: FramebufferOptions): GLFramebuffer;
+    /**
+     * Fill the current framebuffer with a solid color.
+     * This sets the canvas background color in the render state and clears the framebuffer.
+     * If only one value is provided, it's used for all RGB components.
+     *
+     * @param r - Red component (0-255)
+     * @param g - Green component (0-255), defaults to r if not provided
+     * @param b - Blue component (0-255), defaults to r if not provided
+     * @param a - Alpha component (0-255), defaults to 255 if not provided
+     */
+    $background(r: number, g?: number, b?: number, a?: number): void;
+    /**
+     * Clear the current framebuffer to a specified color.
+     * Color components should be in the range [0, 1].
+     *
+     * @param r - Red component (0-1), defaults to 0
+     * @param g - Green component (0-1), defaults to 0
+     * @param b - Blue component (0-1), defaults to 0
+     * @param a - Alpha component (0-1), defaults to 0
+     */
+    $clear(r?: number, g?: number, b?: number, a?: number): void;
+    /**
+     * Reset the viewport to match the canvas dimensions.
+     * This ensures the viewport is synchronized with the canvas size, which is
+     * important after canvas resize operations.
+     */
+    $resetViewport(): void;
+    /**
+     * Flush all batched instances for instanced rendering.
+     * This must be called at the end of each frame to actually render all batched geometry.
+     * The method processes the entire draw queue and renders all primitives that were
+     * queued during the frame.
+     */
+    $flushInstances(): void;
+    /**
+     * Dispose of all WebGL resources managed by this renderer.
+     * This releases buffers, shaders, geometries, and other GPU resources.
+     * This method is idempotent and safe to call multiple times.
+     * After disposal, the renderer should not be used.
+     */
+    $dispose(): void;
+}

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

@@ -0,0 +1,17 @@
+/**
+ * Instanced arc (pie segment) geometry implementation
+ */
+import type { InstanceBatch } from '../../batching/InstanceBatch';
+import { type ArcParams } from '../../types/GeometryTypes';
+import { BaseGeometry } from '../BaseGeometry';
+import type { IRenderState } from '../../state/RenderState';
+/**
+ * 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<ArcParams> {
+    constructor(gl: WebGL2RenderingContext, batch: InstanceBatch);
+    /** Add an arc instance (filled pie segment) */
+    $addInstance(params: ArcParams, renderState: IRenderState): number;
+}

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

@@ -0,0 +1,23 @@
+/**
+ * Instanced bezier curve geometry implementation
+ */
+import type { InstanceBatch } from '../../batching/InstanceBatch';
+import { type BezierCurveParams } from '../../types/GeometryTypes';
+import { BaseGeometry } from '../BaseGeometry';
+import type { IRenderState } from '../../state/RenderState';
+/**
+ * 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<BezierCurveParams> {
+    constructor(gl: WebGL2RenderingContext, batch: InstanceBatch);
+    /**
+     * Add a bezier curve instance to the batch - TRUE INSTANCED APPROACH
+     */
+    $addInstance(params: BezierCurveParams, renderState: IRenderState): number;
+}

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

@@ -0,0 +1,21 @@
+/**
+ * Instanced ellipse geometry implementation
+ */
+import type { InstanceBatch } from '../../batching/InstanceBatch';
+import { type EllipseParams } from '../../types/GeometryTypes';
+import { BaseGeometry } from '../BaseGeometry';
+import type { IRenderState } from '../../state/RenderState';
+/**
+ * Instanced ellipse geometry renderer.
+ * Batches all ellipse draw calls for efficient GPU rendering.
+ */
+export declare class Ellipse extends BaseGeometry<EllipseParams> {
+    constructor(gl: WebGL2RenderingContext, batch: InstanceBatch);
+    /**
+     * Add an ellipse instance to the batch
+     * @param params Ellipse parameters
+     * @param renderState Current render state
+     * @returns Index of the added instance
+     */
+    $addInstance(params: EllipseParams, renderState: IRenderState): number;
+}

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

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

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

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

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

@@ -0,0 +1,21 @@
+/**
+ * Instanced triangle geometry implementation
+ */
+import type { InstanceBatch } from '../../batching/InstanceBatch';
+import { type TriangleParams } from '../../types/GeometryTypes';
+import { BaseGeometry } from '../BaseGeometry';
+import type { IRenderState } from '../../state/RenderState';
+/**
+ * Instanced triangle geometry renderer.
+ * Batches all triangle draw calls for efficient GPU rendering.
+ */
+export declare class Triangle extends BaseGeometry<TriangleParams> {
+    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: IRenderState): number;
+}

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

@@ -0,0 +1,57 @@
+import type { InstanceBatch } from '../batching/InstanceBatch';
+import { type InstanceData } from '../batching/InstanceData';
+import { type InstanceWriteData } from '../batching/InstanceWriter';
+import type { IGeometry, GeometryType, UnitGeometryData, GeometryParams } from '../types/GeometryTypes';
+import type { IRenderState } from '../state/RenderState';
+/**
+ * Abstract base class for all instanced geometries.
+ * Provides common functionality for instance data creation and batch management.
+ */
+export declare abstract class BaseGeometry<P = GeometryParams> implements IGeometry<P> {
+    protected readonly _gl: WebGL2RenderingContext;
+    protected readonly _batch: InstanceBatch;
+    protected readonly _type: GeometryType;
+    protected readonly _unitGeometry: UnitGeometryData;
+    private _unitBuffer;
+    protected _tempCurveParams0: [number, number, number, number];
+    protected _tempCurveParams1: [number, number, number, number];
+    protected _tempWriteData: InstanceWriteData;
+    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: P, renderState: IRenderState): number;
+    protected _addInstance(instanceData: InstanceData, _rotationCenterX: number, _rotationCenterY: number): number;
+    /**
+     * Write instance data directly to batch buffer (zero-allocation helper).
+     * Handles all common instance data setup to eliminate code duplication.
+     *
+     * @param x - X position
+     * @param y - Y position
+     * @param width - Width
+     * @param height - Height
+     * @param centerX - Rotation center X (in pixels)
+     * @param centerY - Rotation center Y (in pixels)
+     * @param renderState - Current render state
+     * @param geometryData - Optional geometry-specific data (arc angles, bezier points, depth)
+     * @returns Index of the written instance
+     */
+    protected _writeInstance(x: number, y: number, width: number, height: number, renderState: IRenderState, geometryData?: {
+        arcStart?: number;
+        arcStop?: number;
+        cp1x?: number;
+        cp1y?: number;
+        cp2x?: number;
+        cp2y?: number;
+        bezStartX?: number;
+        bezStartY?: number;
+        bezEndX?: number;
+        bezEndY?: number;
+        depth?: number;
+        baseZ?: number;
+    }): number;
+}

package/dist/types/rendering/webgl/geometries/immediate/ImmediateQuad.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Immediate-mode quad renderer for full-screen passes and framebuffer presentation.
+ *
+ * This is NOT an instanced geometry - it's a simple, stateless utility for drawing
+ * a single textured quad immediately. Used primarily for presenting final framebuffer
+ * results to the screen or for filter passes.
+ */
+/**
+ * Simple immediate-mode quad renderer.
+ * No instancing, no batching, just a single quad drawn with vertex positions in NDC.
+ */
+export declare class ImmediateQuad {
+    private _gl;
+    private _vbo;
+    private _vertexData;
+    constructor(gl: WebGL2RenderingContext);
+    /**
+     * Draw a quad immediately with the given pixel coordinates.
+     * Converts pixel coordinates to NDC and renders a textured quad.
+     *
+     * The current shader must be bound before calling this method.
+     *
+     * @param x X position in pixels
+     * @param y Y position in pixels
+     * @param width Width in pixels
+     * @param height Height in pixels
+     */
+    $draw(x: number, y: number, width: number, height: number): void;
+    /**
+     * Dispose of WebGL resources.
+     */
+    $dispose(): void;
+}

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

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

package/dist/types/rendering/webgl/geometries/utils/GeometryDescriptors.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Shared geometry attribute descriptors to eliminate redundant definitions.
+ * All geometries of the same dimensionality (2D/3D) share identical stride and attribute layouts.
+ */
+/**
+ * Unit quad vertex data used by both instanced and immediate quad rendering.
+ * Format: [x, y, u, v] for each vertex (position + texCoord interleaved)
+ * Layout: Two triangles forming a unit square centered at origin from (-0.5,-0.5) to (0.5,0.5)
+ */
+export declare const UNIT_QUAD: Float32Array<ArrayBuffer>;
+/**
+ * Standard 2D geometry attribute descriptor.
+ * Used by: Rectangle, Line, Ellipse, Triangle, Arc, BezierCurve
+ *
+ * Layout: [position.xy, texCoord.uv]
+ * Stride: 16 bytes (4 floats)
+ */
+export declare const GEOMETRY_2D_DESCRIPTOR: {
+    readonly _stride: 16;
+    readonly _primitiveType: 4;
+    readonly _attributes: {
+        readonly _position: {
+            readonly size: 2;
+            readonly offset: 0;
+        };
+        readonly _texCoord: {
+            readonly size: 2;
+            readonly offset: 8;
+        };
+    };
+};

package/dist/types/rendering/webgl/geometries/utils/GeometryGenerator.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Geometry generation utilities for 2D shapes.
+ * 2D geometries use 4 floats per vertex: position.xy + texCoord.uv
+ */
+/**
+ * Generate 2D circle/ellipse vertices.
+ */
+export declare function generateCircleVertices(segments?: number): Float32Array;
+/**
+ * Generate unit arc vertices for 2D arc rendering.
+ */
+export declare function generateArcVertices(segments: number): Float32Array;
+/**
+ * Generate bezier curve geometry (multi-segment for GPU evaluation).
+ */
+export declare function generateBezierVertices(segments?: number): Float32Array;

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

@@ -0,0 +1,19 @@
+export * from './core/Framebuffer';
+export * from './core/Renderer';
+export * from './core/Shader';
+export * from './utils/ViewportCache';
+export * from './geometries/immediate/ImmediateQuad';
+export * from './pipeline';
+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 './batching/InstanceData';
+export { PackedInstanceData, InstanceAttributeLayout } from './batching/InstanceData';
+export { InstanceBatch } from './batching/InstanceBatch';
+export { BaseGeometry } from './geometries/BaseGeometry';
+export { Rectangle } from './geometries/2d/Rectangle';
+export { Line } from './geometries/2d/Line';
+export { Ellipse } from './geometries/2d/Ellipse';
+export { Arc } from './geometries/2d/Arc';
+export { Triangle } from './geometries/2d/Triangle';
+export { BezierCurve } from './geometries/2d/BezierCurve';

package/dist/types/rendering/webgl/materials/Material.d.ts

@@ -0,0 +1,23 @@
+import type { GLShader } from '../core/Shader';
+import type { UniformValue } from '../types/UniformTypes';
+/**
+ * Material defines how geometry should be rendered.
+ * Combines a shader program with uniform parameters.
+ *
+ * Materials are immutable once created to enable safe deduplication and caching.
+ */
+export interface Material {
+    /** Unique material identifier for fast comparison */
+    readonly id: number;
+    /** The shader program to use for rendering */
+    readonly shader: GLShader;
+    /** Uniform values to set when using this material (immutable) */
+    readonly uniforms: Readonly<Record<string, UniformValue>>;
+    /** Hash for fast material comparison and deduplication */
+    readonly hash: number;
+    /**
+     * Whether this is a built-in system material (solid color, copy, etc.)
+     * Built-in materials are never disposed when cleaning up user materials.
+     */
+    readonly isBuiltIn: boolean;
+}

package/dist/types/rendering/webgl/materials/MaterialManager.d.ts

@@ -0,0 +1,56 @@
+import type { Material } from './Material';
+import { GLShader } from '../core/Shader';
+import type { UniformValue } from '../types/UniformTypes';
+/**
+ * Manages material creation, deduplication, and lifecycle.
+ *
+ * Provides:
+ * - Material creation with automatic deduplication
+ * - Built-in materials (solid color, copy, image-to-MRT)
+ * - Transient materials for dynamic uniforms
+ * - Built-in shader management (2D/3D instanced shaders)
+ *
+ * Performance optimizations:
+ * - Material interning: identical materials share the same instance
+ * - Hash-based lookup for O(1) deduplication
+ * - Separate tracking of user vs built-in materials
+ */
+export declare class MaterialManager {
+    private _nextMaterialId;
+    private readonly _shader;
+    private readonly _copyShader;
+    private readonly _solidColorMaterial;
+    private _materialCache;
+    constructor(gl: WebGL2RenderingContext);
+    /**
+     * Get the default 2D solid-color material.
+     * This material uses the standard instanced MRT shader with per-instance colors.
+     */
+    get $solidColorMaterial(): Material;
+    /**
+     * Get the shared copy shader for MRT framebuffers.
+     */
+    get $copyShader(): GLShader;
+    /**
+     * Create a transient material that won't be cached.
+     * Useful for one-off materials with dynamic uniforms that change every frame.
+     *
+     * @param shader - The shader program to use
+     * @param uniforms - Uniform values to set
+     * @returns A new material instance (not cached)
+     */
+    $createTransientMaterial(shader: GLShader, uniforms?: Record<string, UniformValue>): Material;
+    /**
+     * Compute a hash for a shader + uniforms combination.
+     * Used for material deduplication.
+     */
+    private _computeHash;
+    /**
+     * Hash a single uniform value based on its type.
+     */
+    private _hashUniformValue;
+    /**
+     * Dispose of all shaders and materials managed by this manager.
+     */
+    $dispose(): void;
+}

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

@@ -0,0 +1,2 @@
+export type { Material } from './Material';
+export { MaterialManager } from './MaterialManager';

package/dist/types/rendering/webgl/pipeline/MaterialBatchPipeline.d.ts

@@ -0,0 +1,54 @@
+import type { DrawCommand } from '../types/DrawCommand';
+/**
+ * Material-based rendering pipeline with strict draw order preservation.
+ *
+ * Responsibilities:
+ * - Manages all geometry instances (one per type)
+ * - Batches consecutive commands with the same material + geometry type
+ * - Executes instanced draw calls
+ *
+ * Key principles:
+ * - Batches consecutive commands with the same material + geometry type
+ * - NEVER reorders commands (preserves user draw order)
+ * - Single rendering path for all geometry (no special-casing custom shaders)
+ *
+ * Architecture:
+ * 1. Scan commands in insertion order
+ * 2. Group consecutive runs of same material+type into batches
+ * 3. Render each batch with a single instanced draw call
+ *
+ * Performance:
+ * - Best case: All commands use same material → 1 draw call
+ * - Worst case: Alternating materials → same as unbatched
+ * - Real-world: 50-70% reduction in draw calls
+ * - Optimized to avoid per-frame allocations
+ */
+export declare class MaterialBatchPipeline {
+    private _gl;
+    private _geometries;
+    private _geometryAttributeCache;
+    private _currentShader;
+    private _shaderViewportState;
+    private _lastFlushedMaterial;
+    constructor(gl: WebGL2RenderingContext);
+    /**
+     * Execute all queued draw commands in strict order.
+     * Batches consecutive commands with same material+type for efficiency.
+     *
+     * @param commands - Draw commands in user-specified order
+     */
+    $execute(commands: Iterable<DrawCommand>): void;
+    /**
+     * Flush and render the current batch of instances.
+     *
+     * @param geometry - The geometry instance containing accumulated instances
+     * @param material - The material to use for rendering
+     * @param type - The geometry type
+     * @param useOrtho - Whether to use orthographic projection
+     */
+    private _flushBatch;
+    /**
+     * Dispose of pipeline resources (including all geometries).
+     */
+    $dispose(): void;
+}

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

@@ -0,0 +1,7 @@
+/**
+ * WebGL Rendering Pipeline
+ *
+ * This module contains the rendering pipeline architecture that orchestrates
+ * the execution of draw commands through specialized renderers.
+ */
+export { MaterialBatchPipeline } from './MaterialBatchPipeline';