@vib3code/sdk 2.0.1

package/types/render/ShaderProgram.d.ts

@@ -0,0 +1,277 @@
+/**
+ * ShaderProgram TypeScript Definitions
+ * VIB3+ SDK - Shader Compilation Abstraction
+ */
+
+/** Shader stage identifiers */
+export const enum ShaderStage {
+    VERTEX = 'vertex',
+    FRAGMENT = 'fragment',
+    COMPUTE = 'compute'
+}
+
+/** Uniform type identifiers */
+export const enum UniformType {
+    FLOAT = 'float',
+    INT = 'int',
+    BOOL = 'bool',
+    VEC2 = 'vec2',
+    VEC3 = 'vec3',
+    VEC4 = 'vec4',
+    IVEC2 = 'ivec2',
+    IVEC3 = 'ivec3',
+    IVEC4 = 'ivec4',
+    MAT2 = 'mat2',
+    MAT3 = 'mat3',
+    MAT4 = 'mat4',
+    SAMPLER_2D = 'sampler2D',
+    SAMPLER_CUBE = 'samplerCube',
+    SAMPLER_3D = 'sampler3D'
+}
+
+/** Uniform value types */
+export type UniformValue =
+    | number
+    | boolean
+    | number[]
+    | Float32Array
+    | Int32Array;
+
+/** Preprocessor defines map */
+export interface ShaderDefines {
+    [key: string]: number | string | boolean;
+}
+
+/** Shader source options */
+export interface ShaderSourceOptions {
+    entryPoint?: string;
+    defines?: ShaderDefines;
+    includes?: string[];
+}
+
+/**
+ * Shader source with preprocessing support
+ */
+export declare class ShaderSource {
+    readonly stage: ShaderStage;
+    readonly code: string;
+    readonly entryPoint: string;
+    readonly defines: ShaderDefines;
+    readonly includes: string[];
+
+    constructor(
+        stage: ShaderStage,
+        code: string,
+        options?: ShaderSourceOptions
+    );
+
+    /**
+     * Get processed code with defines injected
+     */
+    getProcessedCode(): string;
+}
+
+/**
+ * Uniform descriptor
+ */
+export declare class UniformDescriptor {
+    readonly name: string;
+    readonly type: UniformType;
+    readonly defaultValue: UniformValue | null;
+    readonly arraySize: number;
+    location: any;
+
+    constructor(
+        name: string,
+        type: UniformType,
+        defaultValue?: UniformValue | null
+    );
+}
+
+/**
+ * Vertex attribute descriptor
+ */
+export declare class AttributeDescriptor {
+    readonly name: string;
+    readonly location: number;
+    readonly type: string;
+
+    constructor(name: string, location: number, type?: string);
+}
+
+/** Uniform descriptor input */
+export interface UniformInput {
+    name: string;
+    type: UniformType;
+    defaultValue?: UniformValue;
+}
+
+/** Attribute descriptor input */
+export interface AttributeInput {
+    name: string;
+    location: number;
+    type?: string;
+}
+
+/** Shader program options */
+export interface ShaderProgramOptions {
+    name?: string;
+    vertex: string;
+    fragment: string;
+    defines?: ShaderDefines;
+    uniforms?: UniformInput[];
+    attributes?: AttributeInput[];
+}
+
+/**
+ * Shader program abstraction
+ */
+export declare class ShaderProgram {
+    readonly id: number;
+    readonly name: string;
+    readonly vertexSource: ShaderSource;
+    readonly fragmentSource: ShaderSource;
+    readonly uniforms: UniformDescriptor[];
+    readonly attributes: AttributeDescriptor[];
+    error: string | null;
+
+    constructor(options: ShaderProgramOptions);
+
+    /**
+     * Check if shader is compiled
+     */
+    readonly isCompiled: boolean;
+
+    /**
+     * Get uniform by name
+     */
+    getUniform(name: string): UniformDescriptor | undefined;
+
+    /**
+     * Get attribute by name
+     */
+    getAttribute(name: string): AttributeDescriptor | undefined;
+
+    /**
+     * Add a uniform descriptor
+     */
+    addUniform(
+        name: string,
+        type: UniformType,
+        defaultValue?: UniformValue
+    ): void;
+
+    /**
+     * Add an attribute descriptor
+     */
+    addAttribute(name: string, location: number, type?: string): void;
+
+    /**
+     * Set uniform value (returns true if value changed)
+     */
+    setUniformValue(name: string, value: UniformValue): boolean;
+
+    /**
+     * Get cached uniform value
+     */
+    getUniformValue(name: string): UniformValue | undefined;
+
+    /**
+     * Clear uniform value cache
+     */
+    clearUniformCache(): void;
+
+    /**
+     * Get native handle
+     */
+    getHandle(): any;
+
+    /**
+     * Set native handle
+     */
+    setHandle(handle: any): void;
+
+    /**
+     * Set compilation error
+     */
+    setError(error: string): void;
+
+    /**
+     * Clone shader program
+     */
+    clone(): ShaderProgram;
+
+    /**
+     * Dispose resources
+     */
+    dispose(): void;
+}
+
+/**
+ * 4D shader code library
+ */
+export declare const ShaderLib: {
+    /**
+     * GLSL functions for 6-plane 4D rotation
+     * Includes: rotateXY, rotateXZ, rotateYZ, rotateXW, rotateYW, rotateZW, rotate4D
+     */
+    readonly rotation4D: string;
+
+    /**
+     * GLSL functions for 4D projection
+     * Includes: projectPerspective, projectStereographic, projectOrthographic
+     */
+    readonly projection4D: string;
+
+    /**
+     * Basic 4D vertex shader template
+     */
+    readonly vertex4D: string;
+
+    /**
+     * Basic 4D fragment shader with W-fog
+     */
+    readonly fragment4D: string;
+};
+
+/**
+ * Cache for compiled shaders
+ */
+export declare class ShaderCache {
+    /**
+     * Number of cached shaders
+     */
+    readonly size: number;
+
+    constructor();
+
+    /**
+     * Get or create shader by key
+     */
+    getOrCreate(key: string, factory: () => ShaderProgram): ShaderProgram;
+
+    /**
+     * Get shader by key
+     */
+    get(key: string): ShaderProgram | undefined;
+
+    /**
+     * Set shader by key
+     */
+    set(key: string, shader: ShaderProgram): void;
+
+    /**
+     * Check if shader exists
+     */
+    has(key: string): boolean;
+
+    /**
+     * Clear cache and dispose all shaders
+     */
+    clear(): void;
+}
+
+/**
+ * Global shader cache instance
+ */
+export declare const shaderCache: ShaderCache;

package/types/render/UnifiedRenderBridge.d.ts

@@ -0,0 +1,143 @@
+/**
+ * UnifiedRenderBridge TypeScript Definitions
+ * VIB3+ SDK - WebGL/WebGPU Abstraction Bridge
+ */
+
+import { WebGPUBackend } from './WebGPUBackend';
+
+/** Backend type identifier */
+export type BackendType = 'webgl' | 'webgpu';
+
+/** Shader source bundle for dual-backend compilation */
+export interface ShaderSources {
+    /** GLSL vertex shader source */
+    glslVertex: string;
+    /** GLSL fragment shader source */
+    glslFragment: string;
+    /** WGSL fragment shader source (optional, required for WebGPU) */
+    wgslFragment?: string;
+}
+
+/** Render options for fullscreen quad rendering */
+export interface BridgeRenderOptions {
+    /** Clear color as RGBA 0-1 */
+    clearColor?: [number, number, number, number];
+    /** Whether to clear before drawing (default: true) */
+    clear?: boolean;
+}
+
+/** VIB3+ uniform values accepted by setUniforms */
+export interface VIB3Uniforms {
+    u_time?: number;
+    u_resolution?: [number, number];
+    u_geometry?: number;
+    u_rot4dXY?: number;
+    u_rot4dXZ?: number;
+    u_rot4dYZ?: number;
+    u_rot4dXW?: number;
+    u_rot4dYW?: number;
+    u_rot4dZW?: number;
+    u_dimension?: number;
+    u_gridDensity?: number;
+    u_morphFactor?: number;
+    u_chaos?: number;
+    u_speed?: number;
+    u_hue?: number;
+    u_intensity?: number;
+    u_saturation?: number;
+    u_mouseIntensity?: number;
+    u_clickIntensity?: number;
+    u_bass?: number;
+    u_mid?: number;
+    u_high?: number;
+    u_layerScale?: number;
+    u_layerOpacity?: number;
+    u_layerColor?: [number, number, number];
+    u_densityMult?: number;
+    u_speedMult?: number;
+    [key: string]: number | number[] | boolean | undefined;
+}
+
+/** Bridge creation options */
+export interface BridgeCreateOptions {
+    /** Try WebGPU first (default: true) */
+    preferWebGPU?: boolean;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+
+/**
+ * Pack VIB3+ parameters into a Float32Array for WebGPU uniform buffer.
+ * Layout matches VIB3Uniforms struct in WGSL (256 bytes).
+ */
+export declare function packVIB3Uniforms(uniforms: VIB3Uniforms): Float32Array;
+
+/**
+ * UnifiedRenderBridge - Connects VIB3+ visualization systems to WebGL/WebGPU backends.
+ *
+ * All three VIB3+ visualization systems (Quantum, Faceted, Holographic) use the same
+ * rendering pattern: procedural fragment shaders on a fullscreen quad. This bridge
+ * abstracts that pattern so systems can render identically on either backend.
+ */
+export declare class UnifiedRenderBridge {
+    readonly canvas: HTMLCanvasElement;
+    readonly backendType: BackendType;
+    readonly backend: WebGLRenderingContext | WebGL2RenderingContext | WebGPUBackend;
+
+    constructor(
+        canvas: HTMLCanvasElement,
+        backendType: BackendType,
+        backend: WebGLRenderingContext | WebGL2RenderingContext | WebGPUBackend
+    );
+
+    /**
+     * Create a UnifiedRenderBridge with automatic backend selection.
+     * Tries WebGPU first (if preferred), falls back to WebGL.
+     */
+    static create(
+        canvas: HTMLCanvasElement,
+        options?: BridgeCreateOptions
+    ): Promise<UnifiedRenderBridge>;
+
+    /** Get the active backend type */
+    getBackendType(): BackendType;
+
+    /** Check if the bridge is initialized */
+    readonly initialized: boolean;
+
+    /**
+     * Compile a shader program for a named visualization.
+     * For WebGL: compiles GLSL vertex + fragment shaders.
+     * For WebGPU: compiles WGSL fragment shader with fullscreen pipeline.
+     */
+    compileShader(name: string, sources: ShaderSources): boolean;
+
+    /**
+     * Set uniforms for the next render call.
+     * Accepts a flat object with uniform names as keys.
+     */
+    setUniforms(uniforms: VIB3Uniforms): void;
+
+    /**
+     * Render a fullscreen quad using the named shader program.
+     */
+    render(name: string, options?: BridgeRenderOptions): void;
+
+    /**
+     * Resize the rendering surface.
+     */
+    resize(width: number, height: number, pixelRatio?: number): void;
+
+    /**
+     * Get the raw WebGL context or WebGPU backend for advanced usage.
+     */
+    getRawBackend(): WebGLRenderingContext | WebGL2RenderingContext | WebGPUBackend;
+
+    /** Dispose of all resources */
+    dispose(): void;
+}
+
+/** Check if WebGPU is available in the current environment */
+export declare function canUseWebGPU(): boolean;
+
+export { WGSLShaderLib } from './WebGPUBackend';

package/types/render/WebGLBackend.d.ts

@@ -0,0 +1,168 @@
+/**
+ * WebGLBackend TypeScript Definitions
+ * VIB3+ SDK - WebGL 2.0 Rendering Backend
+ */
+
+import { RenderBackend } from './RenderCommand';
+import { RenderState } from './RenderState';
+
+/** WebGL context options */
+export interface WebGLContextOptions {
+    alpha?: boolean;
+    depth?: boolean;
+    stencil?: boolean;
+    antialias?: boolean;
+    premultipliedAlpha?: boolean;
+    preserveDrawingBuffer?: boolean;
+    powerPreference?: 'default' | 'high-performance' | 'low-power';
+    failIfMajorPerformanceCaveat?: boolean;
+}
+
+/** Backend options */
+export interface WebGLBackendOptions extends WebGLContextOptions {
+    debug?: boolean;
+}
+
+/** Buffer descriptor */
+export interface BufferDescriptor {
+    data?: ArrayBufferView;
+    size?: number;
+    usage?: 'vertex' | 'index';
+    dynamic?: boolean;
+}
+
+/** GPU buffer handle */
+export interface GPUBuffer {
+    _handle: WebGLBuffer | null;
+    _target: number;
+    size: number;
+    usage: string;
+}
+
+/** WebGL extensions */
+export interface WebGLExtensions {
+    colorBufferFloat: any;
+    floatBlend: any;
+    textureFilterAnisotropic: any;
+    debugRendererInfo: any;
+    loseContext: any;
+    parallelShaderCompile: any;
+}
+
+/** Backend statistics */
+export interface BackendStats {
+    drawCalls: number;
+    stateChanges: number;
+    shaderSwitches: number;
+    textureBinds: number;
+}
+
+/**
+ * WebGL 2.0 rendering backend
+ */
+export declare class WebGLBackend implements RenderBackend {
+    readonly gl: WebGL2RenderingContext;
+    readonly debug: boolean;
+    readonly extensions: WebGLExtensions;
+
+    constructor(gl: WebGL2RenderingContext, options?: WebGLBackendOptions);
+
+    /**
+     * Clear framebuffer
+     */
+    clear(command: any): void;
+
+    /**
+     * Set render state
+     */
+    setState(state: RenderState): void;
+
+    /**
+     * Set viewport
+     */
+    setViewport(x: number, y: number, width: number, height: number): void;
+
+    /**
+     * Bind shader program
+     */
+    bindShader(shader: any): void;
+
+    /**
+     * Set shader uniform
+     */
+    setUniform(name: string, value: any, type?: string): void;
+
+    /**
+     * Bind texture to slot
+     */
+    bindTexture(texture: any, slot?: number): void;
+
+    /**
+     * Bind vertex array object
+     */
+    bindVertexArray(vao: any): void;
+
+    /**
+     * Bind render target (framebuffer)
+     */
+    bindRenderTarget(target: any): void;
+
+    /**
+     * Draw non-indexed primitives
+     */
+    draw(command: any): void;
+
+    /**
+     * Draw indexed primitives
+     */
+    drawIndexed(command: any): void;
+
+    /**
+     * Draw instanced primitives
+     */
+    drawInstanced(command: any): void;
+
+    /**
+     * Draw indexed instanced primitives
+     */
+    drawIndexedInstanced(command: any): void;
+
+    /**
+     * Create a GPU buffer
+     */
+    createBuffer(descriptor: BufferDescriptor): GPUBuffer;
+
+    /**
+     * Update buffer data
+     */
+    updateBuffer(buffer: GPUBuffer, data: ArrayBufferView, offset?: number): void;
+
+    /**
+     * Delete buffer
+     */
+    deleteBuffer(buffer: GPUBuffer): void;
+
+    /**
+     * Get render statistics
+     */
+    getStats(): BackendStats;
+
+    /**
+     * Reset statistics
+     */
+    resetStats(): void;
+
+    /**
+     * Dispose all resources
+     */
+    dispose(): void;
+}
+
+/**
+ * Create WebGL 2.0 backend from canvas
+ * @returns Backend instance or null if WebGL 2.0 is not supported
+ */
+export declare function createWebGLBackend(
+    canvas: HTMLCanvasElement,
+    options?: WebGLBackendOptions
+): WebGLBackend | null;