@codexo/exojs 0.8.2 → 0.8.4

package/dist/esm/rendering/mesh/MeshShader.d.ts

@@ -0,0 +1,183 @@
+import type { RenderTexture } from '@/rendering/texture/RenderTexture';
+import type { Texture } from '@/rendering/texture/Texture';
+/**
+ * Uniform value passed to a custom mesh shader. Scalars and small tuples
+ * auto-marshal to the appropriate `Float32Array`/`Int32Array` for the
+ * backend's uniform call. `Texture`/`RenderTexture` values are bound to
+ * texture slots starting at slot 1 — slot 0 is reserved for the mesh's
+ * own `texture`.
+ */
+export type MeshShaderUniformValue = number | readonly [number, number] | readonly [number, number, number] | readonly [number, number, number, number] | Float32Array | Int32Array | Texture | RenderTexture;
+/**
+ * Construction options for {@link MeshShader}.
+ *
+ * At least one language must be supplied. Provide `glsl` for WebGL2,
+ * `wgsl` for WebGPU, or both for backend-portable meshes. The shader
+ * is compiled lazily on first use against the active backend; an
+ * unsupported backend at draw time throws with a clear error.
+ */
+export interface MeshShaderOptions {
+    /**
+     * GLSL ES 3.00 sources for the WebGL2 backend. Both `vertex` and
+     * `fragment` are required when `glsl` is supplied.
+     */
+    readonly glsl?: {
+        readonly vertex: string;
+        readonly fragment: string;
+    };
+    /**
+     * WGSL source for the WebGPU backend. Vertex and fragment entry
+     * points live in the same source file (WGSL convention).
+     */
+    readonly wgsl?: string;
+    /** Initial uniform values; mutate per frame via {@link MeshShader.uniforms}. */
+    readonly uniforms?: Record<string, MeshShaderUniformValue>;
+}
+/**
+ * Custom shader pair attached to a {@link Mesh}.
+ *
+ * One `MeshShader` instance can be shared across many meshes; renderers
+ * cache compiled programs/pipelines on the instance reference. Call
+ * {@link destroy} when the shader is no longer needed to release the
+ * cached GPU resources on every backend the shader was used on.
+ *
+ * # Vertex layout
+ *
+ * The vertex layout is fixed and shared with the default mesh shader,
+ * so custom vertex shaders MUST pin the standard attribute locations:
+ *
+ * ## GLSL (location-qualified)
+ *
+ * ```glsl
+ * layout(location = 0) in vec2 a_position;
+ * layout(location = 1) in vec2 a_texcoord;
+ * layout(location = 2) in vec4 a_color;
+ * ```
+ *
+ * ## WGSL (location-qualified)
+ *
+ * ```wgsl
+ * struct VertexInput {
+ *     @location(0) position: vec2<f32>,
+ *     @location(1) texcoord: vec2<f32>,
+ *     @location(2) color: vec4<f32>,
+ * };
+ * ```
+ *
+ * # Auto-bound uniforms
+ *
+ * The renderer auto-binds these when the shader declares them. Declared
+ * but unused is fine; absent is fine too. Both backends carry the same
+ * logical uniforms, only the binding scheme differs.
+ *
+ * ## GLSL
+ *
+ * ```glsl
+ * uniform mat3 u_projection;   // active view's projection
+ * uniform mat3 u_translation;  // mesh's global transform
+ * uniform vec4 u_tint;         // mesh.tint as RGBA in 0..1
+ * uniform sampler2D u_texture; // bound to texture slot 0
+ * ```
+ *
+ * ## WGSL
+ *
+ * ```wgsl
+ * struct MeshUniforms {
+ *     projection: mat3x3<f32>,
+ *     translation: mat3x3<f32>,
+ *     tint: vec4<f32>,
+ * };
+ *
+ * @group(0) @binding(0) var<uniform> u_mesh: MeshUniforms;
+ *
+ * @group(1) @binding(0) var u_texture: texture_2d<f32>;
+ * @group(1) @binding(1) var u_sampler: sampler;
+ * ```
+ *
+ * # User uniforms
+ *
+ * Anything in {@link uniforms} is set after the auto-binds. `Texture`/
+ * `RenderTexture` values claim slots 1..N (slot 0 belongs to the mesh).
+ *
+ * ## WGSL user-uniform contract
+ *
+ * User uniforms live in `@group(2)`:
+ *
+ * - `@group(2) @binding(0) var<uniform> u_user: <UserUniformsStruct>;`
+ *   for the packed scalar/vector/matrix uniforms.
+ * - `@group(2) @binding(N)` for each `Texture`/`RenderTexture` uniform,
+ *   in declaration order, alongside its sampler at `@binding(N+1)`.
+ */
+export declare class MeshShader {
+    /**
+     * Mutable user uniform values. Mutate between frames to drive animated
+     * effects; the renderer reads from this map every draw.
+     *
+     *   shader.uniforms.uTime = performance.now() / 1000;
+     *   shader.uniforms.uColor = [1, 0.5, 0, 1];
+     */
+    uniforms: Record<string, MeshShaderUniformValue>;
+    /** GLSL source pair for the WebGL2 backend, or `null` if not provided. */
+    readonly glsl: {
+        readonly vertex: string;
+        readonly fragment: string;
+    } | null;
+    /** WGSL source for the WebGPU backend, or `null` if not provided. */
+    readonly wgsl: string | null;
+    private readonly _disposeCallbacks;
+    constructor(options: MeshShaderOptions);
+    /**
+     * Convenience setter equivalent to `shader.uniforms[name] = value`.
+     * Provided for symmetry with engine APIs that prefer explicit methods
+     * over property mutation.
+     */
+    setUniform(name: string, value: MeshShaderUniformValue): void;
+    /**
+     * Reflect declared uniforms from each language's source. Returns a per-
+     * language map of uniform-name → declared type, parsed from the shader
+     * sources via lightweight regex (not a full GLSL/WGSL grammar). Texture
+     * uniforms (`sampler2D`/`texture_2d`) are included; sampler bindings
+     * are not (they pair with textures by binding index).
+     *
+     * Reflection is best-effort and intended for CI drift-checks and editor
+     * tooling, not for runtime uniform binding decisions. The renderers do
+     * NOT consult this map; they bind uniforms by name from {@link uniforms}
+     * and let the underlying API resolve declared-but-unused entries.
+     */
+    getDeclaredUniforms(): {
+        glsl: Record<string, string>;
+        wgsl: Record<string, string>;
+    };
+    /**
+     * Compare declared uniform names between the GLSL and WGSL sources.
+     * Returns lists of names declared in only one language. Use in CI to
+     * catch drift when both languages should expose the same logical
+     * uniforms. When only one language is provided, returns empty arrays.
+     *
+     * Auto-bound uniforms (`u_projection`, `u_translation`, `u_tint`,
+     * `u_texture`) are excluded from the comparison since the GLSL source
+     * declares them at the top-level uniform scope while the WGSL source
+     * receives them via the `@group(0)` mesh-uniforms struct and the
+     * `@group(1)` texture binding.
+     */
+    detectUniformDrift(): {
+        onlyInGlsl: readonly string[];
+        onlyInWgsl: readonly string[];
+    };
+    /**
+     * Release GPU resources cached against this `MeshShader` on every
+     * backend that has compiled it. Safe to call multiple times. After
+     * destroy, the shader can still be re-used — renderers will recompile
+     * on next draw — but typical usage is to drop the reference.
+     */
+    destroy(): void;
+    /**
+     * Internal hook for renderers to register a per-shader-instance cleanup
+     * callback (release compiled program, pipeline, or bind groups). The
+     * callback fires on {@link destroy}; renderers MUST also tolerate the
+     * shader being garbage-collected without destroy ever being called.
+     *
+     * @internal
+     */
+    _onDispose(callback: () => void): void;
+}

package/dist/esm/rendering/mesh/MeshShader.js

@@ -0,0 +1,231 @@
+/**
+ * Custom shader pair attached to a {@link Mesh}.
+ *
+ * One `MeshShader` instance can be shared across many meshes; renderers
+ * cache compiled programs/pipelines on the instance reference. Call
+ * {@link destroy} when the shader is no longer needed to release the
+ * cached GPU resources on every backend the shader was used on.
+ *
+ * # Vertex layout
+ *
+ * The vertex layout is fixed and shared with the default mesh shader,
+ * so custom vertex shaders MUST pin the standard attribute locations:
+ *
+ * ## GLSL (location-qualified)
+ *
+ * ```glsl
+ * layout(location = 0) in vec2 a_position;
+ * layout(location = 1) in vec2 a_texcoord;
+ * layout(location = 2) in vec4 a_color;
+ * ```
+ *
+ * ## WGSL (location-qualified)
+ *
+ * ```wgsl
+ * struct VertexInput {
+ *     @location(0) position: vec2<f32>,
+ *     @location(1) texcoord: vec2<f32>,
+ *     @location(2) color: vec4<f32>,
+ * };
+ * ```
+ *
+ * # Auto-bound uniforms
+ *
+ * The renderer auto-binds these when the shader declares them. Declared
+ * but unused is fine; absent is fine too. Both backends carry the same
+ * logical uniforms, only the binding scheme differs.
+ *
+ * ## GLSL
+ *
+ * ```glsl
+ * uniform mat3 u_projection;   // active view's projection
+ * uniform mat3 u_translation;  // mesh's global transform
+ * uniform vec4 u_tint;         // mesh.tint as RGBA in 0..1
+ * uniform sampler2D u_texture; // bound to texture slot 0
+ * ```
+ *
+ * ## WGSL
+ *
+ * ```wgsl
+ * struct MeshUniforms {
+ *     projection: mat3x3<f32>,
+ *     translation: mat3x3<f32>,
+ *     tint: vec4<f32>,
+ * };
+ *
+ * @group(0) @binding(0) var<uniform> u_mesh: MeshUniforms;
+ *
+ * @group(1) @binding(0) var u_texture: texture_2d<f32>;
+ * @group(1) @binding(1) var u_sampler: sampler;
+ * ```
+ *
+ * # User uniforms
+ *
+ * Anything in {@link uniforms} is set after the auto-binds. `Texture`/
+ * `RenderTexture` values claim slots 1..N (slot 0 belongs to the mesh).
+ *
+ * ## WGSL user-uniform contract
+ *
+ * User uniforms live in `@group(2)`:
+ *
+ * - `@group(2) @binding(0) var<uniform> u_user: <UserUniformsStruct>;`
+ *   for the packed scalar/vector/matrix uniforms.
+ * - `@group(2) @binding(N)` for each `Texture`/`RenderTexture` uniform,
+ *   in declaration order, alongside its sampler at `@binding(N+1)`.
+ */
+class MeshShader {
+    /**
+     * Mutable user uniform values. Mutate between frames to drive animated
+     * effects; the renderer reads from this map every draw.
+     *
+     *   shader.uniforms.uTime = performance.now() / 1000;
+     *   shader.uniforms.uColor = [1, 0.5, 0, 1];
+     */
+    uniforms;
+    /** GLSL source pair for the WebGL2 backend, or `null` if not provided. */
+    glsl;
+    /** WGSL source for the WebGPU backend, or `null` if not provided. */
+    wgsl;
+    _disposeCallbacks = new Set();
+    constructor(options) {
+        if (options.glsl === undefined && options.wgsl === undefined) {
+            throw new Error('MeshShader requires at least one of `glsl` or `wgsl`.');
+        }
+        if (options.glsl !== undefined) {
+            if (typeof options.glsl.vertex !== 'string' || options.glsl.vertex.length === 0) {
+                throw new Error('MeshShader.glsl.vertex must be a non-empty string.');
+            }
+            if (typeof options.glsl.fragment !== 'string' || options.glsl.fragment.length === 0) {
+                throw new Error('MeshShader.glsl.fragment must be a non-empty string.');
+            }
+        }
+        if (options.wgsl !== undefined && (typeof options.wgsl !== 'string' || options.wgsl.length === 0)) {
+            throw new Error('MeshShader.wgsl must be a non-empty string.');
+        }
+        this.glsl = options.glsl ?? null;
+        this.wgsl = options.wgsl ?? null;
+        this.uniforms = { ...(options.uniforms ?? {}) };
+    }
+    /**
+     * Convenience setter equivalent to `shader.uniforms[name] = value`.
+     * Provided for symmetry with engine APIs that prefer explicit methods
+     * over property mutation.
+     */
+    setUniform(name, value) {
+        this.uniforms[name] = value;
+    }
+    /**
+     * Reflect declared uniforms from each language's source. Returns a per-
+     * language map of uniform-name → declared type, parsed from the shader
+     * sources via lightweight regex (not a full GLSL/WGSL grammar). Texture
+     * uniforms (`sampler2D`/`texture_2d`) are included; sampler bindings
+     * are not (they pair with textures by binding index).
+     *
+     * Reflection is best-effort and intended for CI drift-checks and editor
+     * tooling, not for runtime uniform binding decisions. The renderers do
+     * NOT consult this map; they bind uniforms by name from {@link uniforms}
+     * and let the underlying API resolve declared-but-unused entries.
+     */
+    getDeclaredUniforms() {
+        return {
+            glsl: this.glsl !== null ? parseGlslUniforms(this.glsl.vertex, this.glsl.fragment) : {},
+            wgsl: this.wgsl !== null ? parseWgslUniforms(this.wgsl) : {},
+        };
+    }
+    /**
+     * Compare declared uniform names between the GLSL and WGSL sources.
+     * Returns lists of names declared in only one language. Use in CI to
+     * catch drift when both languages should expose the same logical
+     * uniforms. When only one language is provided, returns empty arrays.
+     *
+     * Auto-bound uniforms (`u_projection`, `u_translation`, `u_tint`,
+     * `u_texture`) are excluded from the comparison since the GLSL source
+     * declares them at the top-level uniform scope while the WGSL source
+     * receives them via the `@group(0)` mesh-uniforms struct and the
+     * `@group(1)` texture binding.
+     */
+    detectUniformDrift() {
+        if (this.glsl === null || this.wgsl === null) {
+            return { onlyInGlsl: [], onlyInWgsl: [] };
+        }
+        const declared = this.getDeclaredUniforms();
+        const glslNames = new Set(Object.keys(declared.glsl).filter(n => !autoBoundUniformNames.has(n)));
+        const wgslNames = new Set(Object.keys(declared.wgsl).filter(n => !autoBoundUniformNames.has(n)));
+        const onlyInGlsl = [];
+        const onlyInWgsl = [];
+        for (const name of glslNames) {
+            if (!wgslNames.has(name))
+                onlyInGlsl.push(name);
+        }
+        for (const name of wgslNames) {
+            if (!glslNames.has(name))
+                onlyInWgsl.push(name);
+        }
+        return { onlyInGlsl, onlyInWgsl };
+    }
+    /**
+     * Release GPU resources cached against this `MeshShader` on every
+     * backend that has compiled it. Safe to call multiple times. After
+     * destroy, the shader can still be re-used — renderers will recompile
+     * on next draw — but typical usage is to drop the reference.
+     */
+    destroy() {
+        for (const callback of this._disposeCallbacks) {
+            callback();
+        }
+        this._disposeCallbacks.clear();
+    }
+    /**
+     * Internal hook for renderers to register a per-shader-instance cleanup
+     * callback (release compiled program, pipeline, or bind groups). The
+     * callback fires on {@link destroy}; renderers MUST also tolerate the
+     * shader being garbage-collected without destroy ever being called.
+     *
+     * @internal
+     */
+    _onDispose(callback) {
+        this._disposeCallbacks.add(callback);
+    }
+}
+const autoBoundUniformNames = new Set(['u_projection', 'u_translation', 'u_tint', 'u_texture', 'u_mesh']);
+const glslUniformPattern = /\buniform\s+(?:mediump\s+|highp\s+|lowp\s+|)(\w+)\s+(\w+)[^;]*;/g;
+const wgslUserUniformPattern = /@group\(\s*2\s*\)\s*@binding\(\s*\d+\s*\)\s*var(?:<[^>]+>|)\s+(\w+)\s*:\s*([^;]+);/g;
+/**
+ * Strip line and block comments from a shader source so the uniform
+ * regexes don't match commented-out declarations. Conservative: works
+ * for both GLSL and WGSL syntax (both use `//` and `/* ... *\/`).
+ */
+function stripComments(source) {
+    return source.replaceAll(/\/\*[\s\S]*?\*\//g, '').replaceAll(/\/\/[^\n]*/g, '');
+}
+function parseGlslUniforms(vertex, fragment) {
+    const result = {};
+    for (const source of [vertex, fragment]) {
+        const stripped = stripComments(source);
+        glslUniformPattern.lastIndex = 0;
+        let match;
+        while ((match = glslUniformPattern.exec(stripped)) !== null) {
+            const [, type, name] = match;
+            result[name] = type;
+        }
+    }
+    return result;
+}
+function parseWgslUniforms(source) {
+    const result = {};
+    const stripped = stripComments(source);
+    // User uniforms in @group(2). Each user-uniform binding is either:
+    //   - var<uniform> u_user: SomeStruct;
+    //   - var u_extraTex: texture_2d<f32>;
+    // We extract the name and the (trimmed) type expression.
+    wgslUserUniformPattern.lastIndex = 0;
+    let match;
+    while ((match = wgslUserUniformPattern.exec(stripped)) !== null) {
+        const [, name, type] = match;
+        result[name] = type.trim();
+    }
+    return result;
+}
+
+export { MeshShader };
+//# sourceMappingURL=MeshShader.js.map

package/dist/esm/rendering/mesh/MeshShader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MeshShader.js","sources":["../../../../../src/rendering/mesh/MeshShader.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}

package/dist/esm/rendering/texture/DataTexture.d.ts

@@ -0,0 +1,115 @@
+import type { SamplerOptions } from '@/rendering/texture/Sampler';
+import { Texture } from '@/rendering/texture/Texture';
+/**
+ * Pixel format for {@link DataTexture}.
+ *
+ * - `r8`     — single-channel 8-bit unsigned. Buffer is `Uint8Array`. 1 byte/pixel.
+ * - `r32f`   — single-channel 32-bit float. Buffer is `Float32Array`. 4 bytes/pixel.
+ * - `rgba8`  — 4-channel 8-bit unsigned. Buffer is `Uint8Array`. 4 bytes/pixel.
+ * - `rgba32f`— 4-channel 32-bit float. Buffer is `Float32Array`. 16 bytes/pixel.
+ *
+ * Float formats are core in WebGL2 and WebGPU; no extension probe required.
+ */
+export type DataTextureFormat = 'r8' | 'r32f' | 'rgba8' | 'rgba32f';
+/** Buffer typed-array kind for a given format. */
+export type DataTextureBuffer<F extends DataTextureFormat = DataTextureFormat> = F extends 'r8' | 'rgba8' ? Uint8Array : F extends 'r32f' | 'rgba32f' ? Float32Array : Uint8Array | Float32Array;
+/**
+ * A region of the buffer marked for upload by the next backend sync.
+ * Bounds are pixel coordinates with origin at the top-left.
+ */
+export interface DataTextureDirtyRegion {
+    /** Whether the whole texture should be re-uploaded (covers initial alloc and full {@link DataTexture.commit}). */
+    readonly full: boolean;
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+/** Construction options for {@link DataTexture}. */
+export interface DataTextureOptions {
+    readonly width: number;
+    readonly height: number;
+    readonly format: DataTextureFormat;
+    /**
+     * Optional external buffer. When omitted, an internal buffer is allocated
+     * sized exactly `width * height * channels`. When supplied:
+     * - A `Uint8Array` requires an 8-bit format (`r8`/`rgba8`).
+     * - A `Float32Array` requires a 32-bit float format (`r32f`/`rgba32f`).
+     * - An `ArrayBuffer` is accepted for any format and wrapped in the
+     *   appropriate typed-array kind (zero-copy view, no allocation).
+     *
+     * In all cases the byte length must equal `width * height * channels * bytesPerChannel`,
+     * otherwise the constructor throws.
+     */
+    readonly data?: Uint8Array | Float32Array | ArrayBuffer;
+    /** Sampler overrides; defaults to nearest filtering and clamp-to-edge wrapping. */
+    readonly samplerOptions?: Partial<SamplerOptions>;
+}
+/**
+ * A 2D texture whose pixels live in a CPU-side typed array. Mutate the
+ * `buffer` directly and call {@link commit} to upload the whole array, or
+ * {@link commitRect} to upload a sub-region (cheaper for ring-buffer
+ * patterns like spectrograms).
+ *
+ * `DataTexture` extends {@link Texture}, so any API that accepts a
+ * `Texture` (filter uniforms, mesh textures, custom shader uniforms)
+ * accepts a `DataTexture` unchanged.
+ *
+ * # Default sampler
+ *
+ * `DataTexture` defaults to nearest filtering, clamp-to-edge wrap, no mip
+ * generation, and no premultiply. These match the typical "raw data
+ * lookup" use case where bilinear filtering would corrupt sampled values
+ * (e.g. spectrum bins sampled by index).
+ *
+ * # Bring-your-own buffer
+ *
+ * Pass `data` in options to share an external buffer. Useful for:
+ * - SharedArrayBuffer + Worker pipelines (audio DSP off the main thread)
+ * - Buffer pooling across many small textures
+ * - Interop with WebAssembly memory or other APIs that produce typed-array views
+ *
+ * The buffer reference is fixed for the lifetime of the texture (the
+ * `buffer` property is `readonly`); only its contents may be mutated.
+ *
+ * # Format / buffer correspondence
+ *
+ * The TypeScript type system narrows `buffer` based on `format`:
+ *
+ *   const r8 = new DataTexture({ width: 256, height: 1, format: 'r8' });
+ *   r8.buffer  // Uint8Array
+ *
+ *   const r32f = new DataTexture({ width: 256, height: 1, format: 'r32f' });
+ *   r32f.buffer  // Float32Array
+ */
+export declare class DataTexture<F extends DataTextureFormat = DataTextureFormat> extends Texture {
+    static defaultSamplerOptions: SamplerOptions;
+    readonly format: F;
+    readonly buffer: DataTextureBuffer<F>;
+    private _dirty;
+    constructor(options: DataTextureOptions & {
+        format: F;
+    });
+    /**
+     * Mark the entire buffer for re-upload on next backend sync. Call after
+     * mutating `buffer` contents to flush changes to the GPU.
+     */
+    commit(): this;
+    /**
+     * Mark a sub-region of the buffer dirty for partial upload. More efficient
+     * than {@link commit} for ring-buffer patterns where only one row or column
+     * changes per frame. If a region was already pending, the union is uploaded.
+     *
+     * Coordinates are pixel-space with origin at the top-left. Bounds are clamped
+     * to the texture dimensions; out-of-range rectangles throw.
+     */
+    commitRect(x: number, y: number, width: number, height: number): this;
+    /**
+     * Internal: backend reads the pending dirty region and clears it. Returns
+     * `null` when there is nothing pending. Backends call this once per sync
+     * pass to plan their texSubImage2D / writeTexture operations.
+     *
+     * @internal
+     */
+    _consumeDirtyRegion(): DataTextureDirtyRegion | null;
+}