@meimu/mutracer 0.1.5 → 0.3.0

package/lib/scene/InstanceState.d.ts

@@ -0,0 +1,39 @@
+/** Options for a batch sharing geometry and materials. */
+export interface InstancedMeshOptions {
+    /** Required active instance count; a nonnegative integer. */
+    count: number;
+    /** Column-major local matrices, at least 16 * count floats. Default: count identity matrices. The array is retained. */
+    transforms?: Float32Array;
+    /** Linear RGB multipliers, at least 3 * count floats. Default undefined (white). The array is retained. */
+    colors?: Float32Array;
+}
+export default class InstanceState {
+    /** Local column-major matrices. Default: count identities. Call markTransformsUpdated after element edits. */
+    transforms: Float32Array;
+    /** Active prefix length. Default: constructor count; must fit transforms and colors. Changes are detected by engine.update. */
+    count: number;
+    /** Linear RGB multipliers, 3 floats per instance. Default undefined (white). Call markColorsUpdated after element edits. */
+    colors: Float32Array | undefined;
+    /** Advanced by any update notification. Default 0. */
+    get version(): number;
+    private _version;
+    private _transformVersion;
+    private _colorVersion;
+    constructor(options: InstancedMeshOptions);
+    /**
+     * Notify edits to both local matrices and colors for all active instances.
+     * Advances version once. Does not notify geometry or material edits. Returns this.
+     * Use the dedicated methods for single-property edits to avoid unnecessary work.
+     */
+    markUpdated(): this;
+    /**
+     * Notify edited local matrices, avoiding copies of unchanged colors.
+     * Defaults: start 0, count all active matrices from start. Returns this.
+     */
+    markTransformsUpdated(start?: number, count?: number): this;
+    /**
+     * Notify edited colors without copying matrices or updating BVHs.
+     * Defaults: start 0, count all active instances from start. Returns this.
+     */
+    markColorsUpdated(start?: number, count?: number): this;
+}

package/lib/scene/InstanceState.js

@@ -0,0 +1,77 @@
+// Shared instance storage and revisions; the browser facade delegates to this state.
+export default class InstanceState {
+    /** Local column-major matrices. Default: count identities. Call markTransformsUpdated after element edits. */
+    transforms;
+    /** Active prefix length. Default: constructor count; must fit transforms and colors. Changes are detected by engine.update. */
+    count;
+    /** Linear RGB multipliers, 3 floats per instance. Default undefined (white). Call markColorsUpdated after element edits. */
+    colors;
+    /** Advanced by any update notification. Default 0. */
+    get version() { return this._version; }
+    _version = 0;
+    _transformVersion = 0;
+    _colorVersion = 0;
+    /** @internal */
+    get transformsVersion() { return this._transformVersion; }
+    /** @internal */
+    get colorsVersion() { return this._colorVersion; }
+    constructor(options) {
+        this.count = options.count;
+        this.transforms = options.transforms ?? new Float32Array(this.count * 16);
+        this.colors = options.colors;
+        this.validate();
+        if (!options.transforms)
+            for (let i = 0; i < this.count; i++) {
+                const offset = i * 16;
+                this.transforms[offset] = this.transforms[offset + 5] = this.transforms[offset + 10] = this.transforms[offset + 15] = 1;
+            }
+    }
+    /**
+     * Notify edits to both local matrices and colors for all active instances.
+     * Advances version once. Does not notify geometry or material edits. Returns this.
+     * Use the dedicated methods for single-property edits to avoid unnecessary work.
+     */
+    markUpdated() {
+        this.validate();
+        this._transformVersion++;
+        this._colorVersion++;
+        this._version++;
+        return this;
+    }
+    /**
+     * Notify edited local matrices, avoiding copies of unchanged colors.
+     * Defaults: start 0, count all active matrices from start. Returns this.
+     */
+    markTransformsUpdated(start = 0, count = this.count - start) {
+        this.validate();
+        if (!Number.isInteger(start) || !Number.isInteger(count) || start < 0 || count < 0 || start + count > this.count) {
+            throw new RangeError('Instance transform range must fit the active count.');
+        }
+        this._transformVersion++;
+        this._version++;
+        return this;
+    }
+    /**
+     * Notify edited colors without copying matrices or updating BVHs.
+     * Defaults: start 0, count all active instances from start. Returns this.
+     */
+    markColorsUpdated(start = 0, count = this.count - start) {
+        this.validate();
+        if (!Number.isInteger(start) || !Number.isInteger(count) || start < 0 || count < 0 || start + count > this.count) {
+            throw new RangeError('Instance color range must fit the active count.');
+        }
+        this._colorVersion++;
+        this._version++;
+        return this;
+    }
+    /** @internal */
+    validate() {
+        if (!Number.isInteger(this.count) || this.count < 0 || !(this.transforms instanceof Float32Array) || this.transforms.length < this.count * 16) {
+            throw new RangeError('InstancedMesh requires a nonnegative count and at least 16 * count Float32 transforms.');
+        }
+        if (this.colors !== undefined && (!(this.colors instanceof Float32Array) || this.colors.length < this.count * 3)) {
+            throw new RangeError('InstancedMesh colors must contain at least 3 * count Float32 values.');
+        }
+    }
+}
+//# sourceMappingURL=InstanceState.js.map

package/lib/scene/InstanceState.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"InstanceState.js","sourceRoot":"","sources":["../../src/scene/InstanceState.ts"],"names":[],"mappings":"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","sourcesContent":["/** Options for a batch sharing geometry and materials. */\nexport interface InstancedMeshOptions {\n  /** Required active instance count; a nonnegative integer. */\n  count: number;\n  /** Column-major local matrices, at least 16 * count floats. Default: count identity matrices. The array is retained. */\n  transforms?: Float32Array;\n  /** Linear RGB multipliers, at least 3 * count floats. Default undefined (white). The array is retained. */\n  colors?: Float32Array;\n}\n\n// Shared instance storage and revisions; the browser facade delegates to this state.\nexport default class InstanceState {\n  /** Local column-major matrices. Default: count identities. Call markTransformsUpdated after element edits. */\n  transforms: Float32Array;\n  /** Active prefix length. Default: constructor count; must fit transforms and colors. Changes are detected by engine.update. */\n  count: number;\n  /** Linear RGB multipliers, 3 floats per instance. Default undefined (white). Call markColorsUpdated after element edits. */\n  colors: Float32Array | undefined;\n  /** Advanced by any update notification. Default 0. */\n  get version(): number { return this._version; }\n  private _version = 0;\n  private _transformVersion = 0;\n  private _colorVersion = 0;\n  /** @internal */\n  get transformsVersion(): number { return this._transformVersion; }\n  /** @internal */\n  get colorsVersion(): number { return this._colorVersion; }\n\n  constructor(options: InstancedMeshOptions) {\n    this.count = options.count;\n    this.transforms = options.transforms ?? new Float32Array(this.count * 16);\n    this.colors = options.colors;\n    this.validate();\n    if (!options.transforms) for (let i = 0; i < this.count; i++) {\n      const offset = i * 16;\n      this.transforms[offset] = this.transforms[offset + 5] = this.transforms[offset + 10] = this.transforms[offset + 15] = 1;\n    }\n  }\n  /**\n   * Notify edits to both local matrices and colors for all active instances.\n   * Advances version once. Does not notify geometry or material edits. Returns this.\n   * Use the dedicated methods for single-property edits to avoid unnecessary work.\n   */\n  markUpdated(): this {\n    this.validate();\n    this._transformVersion++; this._colorVersion++; this._version++;\n    return this;\n  }\n  /**\n   * Notify edited local matrices, avoiding copies of unchanged colors.\n   * Defaults: start 0, count all active matrices from start. Returns this.\n   */\n  markTransformsUpdated(start = 0, count = this.count - start): this {\n    this.validate();\n    if (!Number.isInteger(start) || !Number.isInteger(count) || start < 0 || count < 0 || start + count > this.count) {\n      throw new RangeError('Instance transform range must fit the active count.');\n    }\n    this._transformVersion++; this._version++;\n    return this;\n  }\n  /**\n   * Notify edited colors without copying matrices or updating BVHs.\n   * Defaults: start 0, count all active instances from start. Returns this.\n   */\n  markColorsUpdated(start = 0, count = this.count - start): this {\n    this.validate();\n    if (!Number.isInteger(start) || !Number.isInteger(count) || start < 0 || count < 0 || start + count > this.count) {\n      throw new RangeError('Instance color range must fit the active count.');\n    }\n    this._colorVersion++; this._version++;\n    return this;\n  }\n  /** @internal */\n  validate() {\n    if (!Number.isInteger(this.count) || this.count < 0 || !(this.transforms instanceof Float32Array) || this.transforms.length < this.count * 16) {\n      throw new RangeError('InstancedMesh requires a nonnegative count and at least 16 * count Float32 transforms.');\n    }\n    if (this.colors !== undefined && (!(this.colors instanceof Float32Array) || this.colors.length < this.count * 3)) {\n      throw new RangeError('InstancedMesh colors must contain at least 3 * count Float32 values.');\n    }\n  }\n}\n"]}

package/lib/scene/InstancedMesh.d.ts

@@ -1,6 +1,6 @@
 import Mesh from './Mesh.js';
 import Geometry from './Geometry.js';
-import OpenPBRMaterial from './OpenPBRMaterial.js';
+import type OpenPBRMaterial from './OpenPBRMaterial.js';
 /** Options for a batch sharing geometry and materials. */
 export interface InstancedMeshOptions {
     /** Required active instance count; a nonnegative integer. */

package/lib/scene/InstancedMesh.js

@@ -1,6 +1,9 @@
 import Mesh from './Mesh.js';
 /** A batch of instances. World matrices are transform * transforms[i]. */
 export default class InstancedMesh extends Mesh {
+    // A live view over the public own properties keeps engine snapshots independent.
+    /** @internal */
+    get instanceData() { return this; }
     /** Local column-major matrices. Default: count identities. Call markTransformsUpdated after element edits. */
     transforms;
     /** Active prefix length. Default: constructor count; must fit transforms and colors. Changes are detected by engine.update. */

package/lib/scene/InstancedMesh.js.map

@@ -1 +1 @@
-{"version":3,"file":"InstancedMesh.js","sourceRoot":"","sources":["../../src/scene/InstancedMesh.ts"],"names":[],"mappings":"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","sourcesContent":["import Mesh from './Mesh.js';\nimport Geometry from './Geometry.js';\nimport OpenPBRMaterial from './OpenPBRMaterial.js';\n\n/** Options for a batch sharing geometry and materials. */\nexport interface InstancedMeshOptions {\n  /** Required active instance count; a nonnegative integer. */\n  count: number;\n  /** Column-major local matrices, at least 16 * count floats. Default: count identity matrices. The array is retained. */\n  transforms?: Float32Array;\n  /** Linear RGB multipliers, at least 3 * count floats. Default undefined (white). The array is retained. */\n  colors?: Float32Array;\n}\n\n/** A batch of instances. World matrices are transform * transforms[i]. */\nexport default class InstancedMesh extends Mesh {\n  /** Local column-major matrices. Default: count identities. Call markTransformsUpdated after element edits. */\n  transforms: Float32Array;\n  /** Active prefix length. Default: constructor count; must fit transforms and colors. Changes are detected by engine.update. */\n  count: number;\n  /** Linear RGB multipliers, 3 floats per instance. Default undefined (white). Call markColorsUpdated after element edits. */\n  colors: Float32Array | undefined;\n  /** Advanced by any update notification. Default 0. */\n  get version(): number { return this._version; }\n  private _version = 0;\n  private _transformVersion = 0;\n  private _colorVersion = 0;\n  /** @internal */\n  get transformsVersion(): number { return this._transformVersion; }\n  /** @internal */\n  get colorsVersion(): number { return this._colorVersion; }\n\n  constructor(geometry: Geometry, material: OpenPBRMaterial | OpenPBRMaterial[], options: InstancedMeshOptions) {\n    super(geometry, material);\n    this.count = options.count;\n    this.transforms = options.transforms ?? new Float32Array(this.count * 16);\n    this.colors = options.colors;\n    this.validate();\n    if (!options.transforms) for (let i = 0; i < this.count; i++) {\n      const offset = i * 16;\n      this.transforms[offset] = this.transforms[offset + 5] = this.transforms[offset + 10] = this.transforms[offset + 15] = 1;\n    }\n  }\n  /**\n   * Notify edits to both local matrices and colors for all active instances.\n   * Advances version once. Does not notify geometry or material edits. Returns this.\n   * Use the dedicated methods for single-property edits to avoid unnecessary work.\n   */\n  markUpdated(): this {\n    this.validate();\n    this._transformVersion++; this._colorVersion++; this._version++;\n    return this;\n  }\n  /**\n   * Notify edited local matrices, avoiding copies of unchanged colors.\n   * Defaults: start 0, count all active matrices from start. Returns this.\n   */\n  markTransformsUpdated(start = 0, count = this.count - start): this {\n    this.validate();\n    if (!Number.isInteger(start) || !Number.isInteger(count) || start < 0 || count < 0 || start + count > this.count) {\n      throw new RangeError('Instance transform range must fit the active count.');\n    }\n    this._transformVersion++; this._version++;\n    return this;\n  }\n  /**\n   * Notify edited colors without copying matrices or updating BVHs.\n   * Defaults: start 0, count all active instances from start. Returns this.\n   */\n  markColorsUpdated(start = 0, count = this.count - start): this {\n    this.validate();\n    if (!Number.isInteger(start) || !Number.isInteger(count) || start < 0 || count < 0 || start + count > this.count) {\n      throw new RangeError('Instance color range must fit the active count.');\n    }\n    this._colorVersion++; this._version++;\n    return this;\n  }\n  /** @internal */\n  validate() {\n    if (!Number.isInteger(this.count) || this.count < 0 || !(this.transforms instanceof Float32Array) || this.transforms.length < this.count * 16) {\n      throw new RangeError('InstancedMesh requires a nonnegative count and at least 16 * count Float32 transforms.');\n    }\n    if (this.colors !== undefined && (!(this.colors instanceof Float32Array) || this.colors.length < this.count * 3)) {\n      throw new RangeError('InstancedMesh colors must contain at least 3 * count Float32 values.');\n    }\n  }\n}\n"]}
+{"version":3,"file":"InstancedMesh.js","sourceRoot":"","sources":["../../src/scene/InstancedMesh.ts"],"names":[],"mappings":"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","sourcesContent":["import Mesh from './Mesh.js';\nimport Geometry from './Geometry.js';\nimport type OpenPBRMaterial from './OpenPBRMaterial.js';\nimport type { InstanceData } from './MeshState.js';\n\n/** Options for a batch sharing geometry and materials. */\nexport interface InstancedMeshOptions {\n  /** Required active instance count; a nonnegative integer. */\n  count: number;\n  /** Column-major local matrices, at least 16 * count floats. Default: count identity matrices. The array is retained. */\n  transforms?: Float32Array;\n  /** Linear RGB multipliers, at least 3 * count floats. Default undefined (white). The array is retained. */\n  colors?: Float32Array;\n}\n\n/** A batch of instances. World matrices are transform * transforms[i]. */\nexport default class InstancedMesh extends Mesh {\n  // A live view over the public own properties keeps engine snapshots independent.\n  /** @internal */\n  override get instanceData(): InstanceData { return this; }\n  /** Local column-major matrices. Default: count identities. Call markTransformsUpdated after element edits. */\n  transforms: Float32Array;\n  /** Active prefix length. Default: constructor count; must fit transforms and colors. Changes are detected by engine.update. */\n  count: number;\n  /** Linear RGB multipliers, 3 floats per instance. Default undefined (white). Call markColorsUpdated after element edits. */\n  colors: Float32Array | undefined;\n  /** Advanced by any update notification. Default 0. */\n  get version(): number { return this._version; }\n  private _version = 0;\n  private _transformVersion = 0;\n  private _colorVersion = 0;\n  /** @internal */\n  get transformsVersion(): number { return this._transformVersion; }\n  /** @internal */\n  get colorsVersion(): number { return this._colorVersion; }\n\n  constructor(geometry: Geometry, material: OpenPBRMaterial | OpenPBRMaterial[], options: InstancedMeshOptions) {\n    super(geometry, material);\n    this.count = options.count;\n    this.transforms = options.transforms ?? new Float32Array(this.count * 16);\n    this.colors = options.colors;\n    this.validate();\n    if (!options.transforms) for (let i = 0; i < this.count; i++) {\n      const offset = i * 16;\n      this.transforms[offset] = this.transforms[offset + 5] = this.transforms[offset + 10] = this.transforms[offset + 15] = 1;\n    }\n  }\n  /**\n   * Notify edits to both local matrices and colors for all active instances.\n   * Advances version once. Does not notify geometry or material edits. Returns this.\n   * Use the dedicated methods for single-property edits to avoid unnecessary work.\n   */\n  markUpdated(): this {\n    this.validate();\n    this._transformVersion++; this._colorVersion++; this._version++;\n    return this;\n  }\n  /**\n   * Notify edited local matrices, avoiding copies of unchanged colors.\n   * Defaults: start 0, count all active matrices from start. Returns this.\n   */\n  markTransformsUpdated(start = 0, count = this.count - start): this {\n    this.validate();\n    if (!Number.isInteger(start) || !Number.isInteger(count) || start < 0 || count < 0 || start + count > this.count) {\n      throw new RangeError('Instance transform range must fit the active count.');\n    }\n    this._transformVersion++; this._version++;\n    return this;\n  }\n  /**\n   * Notify edited colors without copying matrices or updating BVHs.\n   * Defaults: start 0, count all active instances from start. Returns this.\n   */\n  markColorsUpdated(start = 0, count = this.count - start): this {\n    this.validate();\n    if (!Number.isInteger(start) || !Number.isInteger(count) || start < 0 || count < 0 || start + count > this.count) {\n      throw new RangeError('Instance color range must fit the active count.');\n    }\n    this._colorVersion++; this._version++;\n    return this;\n  }\n  /** @internal */\n  validate() {\n    if (!Number.isInteger(this.count) || this.count < 0 || !(this.transforms instanceof Float32Array) || this.transforms.length < this.count * 16) {\n      throw new RangeError('InstancedMesh requires a nonnegative count and at least 16 * count Float32 transforms.');\n    }\n    if (this.colors !== undefined && (!(this.colors instanceof Float32Array) || this.colors.length < this.count * 3)) {\n      throw new RangeError('InstancedMesh colors must contain at least 3 * count Float32 values.');\n    }\n  }\n}\n"]}

package/lib/scene/MaterialState.d.ts

@@ -0,0 +1,209 @@
+import type { Vec2 } from '../types.js';
+import type { ColorRGB } from '../types.js';
+import type TextureState from './TextureState.js';
+import type { ThinFilmMapChannel } from './thinFilmParameters.js';
+export type UVProjection = 'none' | 'triplanar' | 'spherical' | 'cylindrical';
+export type MaterialAlphaMode = 'auto' | 'opaque' | 'mask' | 'blend';
+export type { MaterialTextureName } from './materialTextureNames.js';
+export default class MaterialState {
+    /** Stable unsigned material ID, excluding 0xFFFFFFFF. Default process-unique monotonic ID; assign before committing the scene. */
+    get aovId(): number;
+    set aovId(value: number);
+    /** Creates a material. Omitted properties use their documented defaults. */
+    constructor(params?: MaterialStateParams);
+    /** Multiplier of diffuse reflection and metallic normal-incidence color; does not scale dielectric specular, transmission or subsurface. Default `1`. */
+    baseWeight: number;
+    /** Diffuse/metal color. Default `[0.8, 0.8, 0.8]`. */
+    baseColor: ColorRGB;
+    /** Oren-Nayar style roughness of the diffuse lobe. Default `0`. */
+    baseDiffuseRoughness: number;
+    /** `0` dielectric, `1` metal. Default `0`. */
+    baseMetalness: number;
+    /** Dielectric specular strength (via IOR) and overall metallic Fresnel multiplier. Default `1`. */
+    specularWeight: number;
+    /** Dielectric specular tint and metallic F82 near-grazing tint. Default `[1, 1, 1]`. */
+    specularColor: ColorRGB;
+    /** Microfacet roughness, `0` mirror to `1` rough; retains source perceptual roughness in `gltf` anisotropy mode. Default `0.3`. */
+    specularRoughness: number;
+    /** Index of refraction. Default `1.5`. */
+    specularIor: number;
+    /**
+     * GGX anisotropy strength, 0 to 1 (requires tangents); native OpenPBR or source glTF strength according to specularAnisotropyModel. Default `0`.
+     * @deprecated Use specularRoughnessAnisotropy.
+     */
+    specularAnisotropy: number;
+    /** `1` makes the dielectric base fully transmissive (glass). Default `0`. */
+    transmissionWeight: number;
+    /** Transmission tint, or the medium color at `transmissionDepth`. Default `[1, 1, 1]`. */
+    transmissionColor: ColorRGB;
+    /** Depth at which `transmissionColor` is reached; `0` tints at the surface. Default `0`. */
+    transmissionDepth: number;
+    /** Volume scattering color of the transmissive medium. Default `[0, 0, 0]`. */
+    transmissionScatter: ColorRGB;
+    /** Henyey-Greenstein anisotropy of the medium, -1 to 1. Default `0`. */
+    transmissionScatterAnisotropy: number;
+    /** Nonnegative dispersion strength; values above `1` are supported. `0` disables wavelength-dependent refraction. Default `0`. */
+    transmissionDispersionScale: number;
+    /** Abbe number controlling dispersion. Default `20`. */
+    transmissionDispersionAbbeNumber: number;
+    /** Subsurface scattering weight. Default `0`. */
+    subsurfaceWeight: number;
+    /** Subsurface color. Default `[0.8, 0.8, 0.8]`. */
+    subsurfaceColor: ColorRGB;
+    /** Mean free path in scene units. Default `1`. */
+    subsurfaceRadius: number;
+    /** Per-channel multiplier of `subsurfaceRadius`. Default `[1, 0.5, 0.25]`. */
+    subsurfaceRadiusScale: ColorRGB;
+    /**
+     * Scattering anisotropy, -1 to 1. Default `0`.
+     * @deprecated Use subsurfaceScatterAnisotropy.
+     */
+    subsurfaceAnisotropy: number;
+    /** Fuzz (sheen) layer weight. Default `0`. */
+    fuzzWeight: number;
+    /** Fuzz reflection color; substrate attenuation uses white fuzz albedo. Default `[1, 1, 1]`. */
+    fuzzColor: ColorRGB;
+    /** Fuzz roughness; imported from Three.js `sheenRoughness`. Default `0.5`. */
+    fuzzRoughness: number;
+    /** Clear coat weight. Default `0`. */
+    coatWeight: number;
+    /** Squared coat transmittance at normal incidence; colors the base and emission, not coat reflection. Default `[1, 1, 1]`. */
+    coatColor: ColorRGB;
+    /** Coat roughness. Default `0`. */
+    coatRoughness: number;
+    /**
+     * OpenPBR GGX coat anisotropy, 0 to 1; uses the base geometry tangent. Default `0`.
+     * @deprecated Use coatRoughnessAnisotropy.
+     */
+    coatAnisotropy: number;
+    /** Coat index of refraction. Default `1.6`. */
+    coatIor: number;
+    /** Internal-reflection darkening: 0 compensates darkening, 1 is physical; absorption remains at 0. Default `1`. */
+    coatDarkening: number;
+    /** Thin-film interference weight (iridescence). Default `0`. */
+    thinFilmWeight: number;
+    /** Film thickness in micrometres; maximum endpoint when thinFilmMap is present. Default `0.5`. */
+    thinFilmThickness: number;
+    /** Film index of refraction. Default `1.4`. */
+    thinFilmIor: number;
+    /** Thickness at a thinFilmMap sample of zero, in micrometres; ignored without a map. May exceed thinFilmThickness. Default `0`. */
+    thinFilmThicknessMinimum: number;
+    /** Linear channel sampled by thinFilmMap. Default `r`. */
+    thinFilmMapChannel: ThinFilmMapChannel;
+    /** Emission color. Default `[1, 1, 1]`. */
+    emissionColor: ColorRGB;
+    /** Emitted radiance scale; `0` disables emission. Default `0`. */
+    emissionLuminance: number;
+    /**
+     * Coverage, `1` opaque. See `alphaMode`. Default `1`.
+     * @deprecated Use geometryOpacity.
+     */
+    opacity: number;
+    /**
+     * Treat the surface as an infinitely thin shell (leaves, paper). Default `false`.
+     * @deprecated Use geometryThinWalled.
+     */
+    thinWalled: boolean;
+    /** Disables geometric back-face culling and permits back-face emission. Default `false`. */
+    doubleSided: boolean;
+    /** Base color texture, multiplied with `baseColor` using Texture color encoding. Default `undefined`. */
+    map?: TextureState;
+    /** Standalone opacity texture sampled from its green channel, matching Three.js. Default `undefined`. */
+    alphaMap?: TextureState;
+    /**
+     * Coverage for surface and shadow rays: `opaque` ignores alpha inputs,
+     * `mask` uses binary alpha testing, `blend` retains fractional coverage.
+     * `auto` derives the mode from the alpha inputs. Default `auto`.
+     */
+    alphaMode: MaterialAlphaMode;
+    /** Alpha-test threshold for `mask` mode; equality is fully covered. Default `0`. */
+    alphaCutoff: number;
+    /** Emission texture multiplied with `emissionColor`. Default `undefined`. */
+    emissiveMap?: TextureState;
+    /** Tangent-space normal map. Default `undefined`. */
+    normalMap?: TextureState;
+    /** Normal map strength per axis. Default `[1, 1]`. */
+    normalScale: Vec2;
+    /** glTF-compatible B=metalness, G=specular roughness texture. Default `undefined`. */
+    metallicRoughnessMap?: TextureState;
+    /** Standalone roughness texture sampled from its green channel. Default `undefined`. */
+    roughnessMap?: TextureState;
+    /** Standalone metalness texture sampled from its blue channel. Default `undefined`. */
+    metalnessMap?: TextureState;
+    /** Multiplies transmission weight using the texture's red channel. Default `undefined`. */
+    transmissionMap?: TextureState;
+    /** Linear thickness-range texture; R and zero minimum preserve multiplication semantics. Default `undefined`. */
+    thinFilmMap?: TextureState;
+    /** Multiplies coatWeight by the linear red channel. Default `undefined`. */
+    coatWeightMap?: TextureState;
+    /** Multiplies coatRoughness by the linear green channel. Default `undefined`. */
+    coatRoughnessMap?: TextureState;
+    /** Multiplies fuzzColor by RGB channels using Texture color encoding. Default `undefined`. */
+    fuzzColorMap?: TextureState;
+    /** Multiplies fuzzRoughness by the linear alpha channel. Default `undefined`. */
+    fuzzRoughnessMap?: TextureState;
+    /** Multiplies specularWeight by the linear alpha channel. Default `undefined`. */
+    specularWeightMap?: TextureState;
+    /** Multiplies specularColor by RGB channels using Texture color encoding. Default `undefined`. */
+    specularColorMap?: TextureState;
+    /** Source convention for base specular anisotropy. `gltf` converts textured roughness and strength before coat roughening; `openpbr` uses native parameters. Default `openpbr`. */
+    specularAnisotropyModel: 'openpbr' | 'gltf';
+    /** Linear RG tangent direction and B strength multiplier for the base specular layer. Default `undefined`. */
+    anisotropyMap?: TextureState;
+    /** Independent tangent-space coat normal in linear RGB. Without a map, coat uses the surface normal before base normal mapping. Default `undefined`. */
+    coatNormalMap?: TextureState;
+    /** XY strength of coatNormalMap; independent of normalScale. Default `[1, 1]`. */
+    coatNormalScale: Vec2;
+    /** Base direction rotation in radians, counter-clockwise in tangent/bitangent space after RG decoding. Default `0`. */
+    specularAnisotropyRotation: number;
+    /** Coat direction rotation in radians relative to the geometry tangent. Default `0`. */
+    coatAnisotropyRotation: number;
+    /** GGX roughness anisotropy in [0, 1]; native OpenPBR or source glTF strength according to specularAnisotropyModel. Requires tangents. Default `0`. */
+    get specularRoughnessAnisotropy(): number;
+    set specularRoughnessAnisotropy(value: number);
+    /** OpenPBR coat GGX roughness anisotropy in [0, 1]. Default `0`. */
+    get coatRoughnessAnisotropy(): number;
+    set coatRoughnessAnisotropy(value: number);
+    /** Subsurface scattering anisotropy in [-1, 1]. Default `0`. */
+    get subsurfaceScatterAnisotropy(): number;
+    set subsurfaceScatterAnisotropy(value: number);
+    /** Surface coverage; alphaMode controls testing and blending. Default `1`. */
+    get geometryOpacity(): number;
+    set geometryOpacity(value: number);
+    /** Treat the surface as an infinitely thin shell. Default `false`. */
+    get geometryThinWalled(): boolean;
+    set geometryThinWalled(value: boolean);
+    /**
+     * Invisible ground that only receives shadows, composited over the
+     * background. Default `false`.
+     */
+    shadowCatcher: boolean;
+    /** Displays emission without scattering or illuminating other surfaces. Default `false`. */
+    unlit: boolean;
+    /** Radius of rounded-edge shading (shader bevel) in scene units. `0` disables it. Default `0`. */
+    bevelSize: number;
+    /** How map alpha is used: ignored, opacity or transmission. Default `opaque`. */
+    mapAlphaUsage: 'opaque' | 'alpha' | 'transmission';
+    /** Procedural UV projection for textures without (good) UVs. Default `none`. */
+    uvProjection: UVProjection;
+    /** UV scale used with `uvProjection`. Default `[1, 1]`. */
+    uvProjectionScale: Vec2;
+    /** Height texture (red channel) for displacement. Default `undefined`. */
+    displacementMap?: TextureState;
+    /** Procedural UV projection for the displacement map. Default `none`. */
+    displacementUvProjection: UVProjection;
+    /** UV scale used with `displacementUvProjection`. Default `1`. */
+    displacementUvProjectionScale: number;
+    /** Height multiplier in mesh-local coordinate units. Default `0.1`. */
+    displacementScale: number;
+    /** Offset added after scaling the height map, along the normal in mesh-local units; requires a displacement map. Default `0`. */
+    displacementBias: number;
+    /** Ray-marching step in mesh-local units; 0 automatically uses abs(displacementScale) / 32. Default `0`. */
+    displacementStepSize: number;
+}
+export { materialAlphaModeConstants } from '../renderer/materialConstants.js';
+export type ResolvedMaterialAlphaMode = Exclude<MaterialAlphaMode, 'auto'>;
+export declare function resolveMaterialAlphaMode(material: MaterialState): ResolvedMaterialAlphaMode;
+export { materialKeys, materialTextureKeys, materialGeometryKeys, materialParamKeys, getMaterialHashKey, resetMaterialTextureId } from './openPbrSchema.js';
+/** Optional material properties; defaults are documented on MaterialState. */
+export type MaterialStateParams = Partial<MaterialState>;

package/lib/scene/MaterialState.js

@@ -0,0 +1,231 @@
+import { allocateAovId, validateAovId } from '../renderer/aov.js';
+import { materialDefault, applyMaterialParams } from './openPbrSchema.js';
+// Shared material state; browser texture types are refined by the public facade.
+const aovIds = new WeakMap();
+export default class MaterialState {
+    /** Stable unsigned material ID, excluding 0xFFFFFFFF. Default process-unique monotonic ID; assign before committing the scene. */
+    get aovId() { return aovIds.get(this); }
+    set aovId(value) { aovIds.set(this, validateAovId(value)); }
+    /** Creates a material. Omitted properties use their documented defaults. */
+    constructor(params = {}) {
+        aovIds.set(this, allocateAovId());
+        applyMaterialParams(this, params);
+        if (params.aovId !== undefined)
+            this.aovId = validateAovId(params.aovId);
+    }
+    // Base
+    /** Multiplier of diffuse reflection and metallic normal-incidence color; does not scale dielectric specular, transmission or subsurface. Default `1`. */
+    baseWeight = materialDefault('baseWeight');
+    /** Diffuse/metal color. Default `[0.8, 0.8, 0.8]`. */
+    baseColor = materialDefault('baseColor');
+    /** Oren-Nayar style roughness of the diffuse lobe. Default `0`. */
+    baseDiffuseRoughness = materialDefault('baseDiffuseRoughness');
+    /** `0` dielectric, `1` metal. Default `0`. */
+    baseMetalness = materialDefault('baseMetalness');
+    // Specular
+    /** Dielectric specular strength (via IOR) and overall metallic Fresnel multiplier. Default `1`. */
+    specularWeight = materialDefault('specularWeight');
+    /** Dielectric specular tint and metallic F82 near-grazing tint. Default `[1, 1, 1]`. */
+    specularColor = materialDefault('specularColor');
+    /** Microfacet roughness, `0` mirror to `1` rough; retains source perceptual roughness in `gltf` anisotropy mode. Default `0.3`. */
+    specularRoughness = materialDefault('specularRoughness');
+    /** Index of refraction. Default `1.5`. */
+    specularIor = materialDefault('specularIor');
+    /**
+     * GGX anisotropy strength, 0 to 1 (requires tangents); native OpenPBR or source glTF strength according to specularAnisotropyModel. Default `0`.
+     * @deprecated Use specularRoughnessAnisotropy.
+     */
+    specularAnisotropy = materialDefault('specularAnisotropy');
+    // Transmission
+    /** `1` makes the dielectric base fully transmissive (glass). Default `0`. */
+    transmissionWeight = materialDefault('transmissionWeight');
+    /** Transmission tint, or the medium color at `transmissionDepth`. Default `[1, 1, 1]`. */
+    transmissionColor = materialDefault('transmissionColor');
+    /** Depth at which `transmissionColor` is reached; `0` tints at the surface. Default `0`. */
+    transmissionDepth = materialDefault('transmissionDepth');
+    /** Volume scattering color of the transmissive medium. Default `[0, 0, 0]`. */
+    transmissionScatter = materialDefault('transmissionScatter');
+    /** Henyey-Greenstein anisotropy of the medium, -1 to 1. Default `0`. */
+    transmissionScatterAnisotropy = materialDefault('transmissionScatterAnisotropy');
+    /** Nonnegative dispersion strength; values above `1` are supported. `0` disables wavelength-dependent refraction. Default `0`. */
+    transmissionDispersionScale = materialDefault('transmissionDispersionScale');
+    /** Abbe number controlling dispersion. Default `20`. */
+    transmissionDispersionAbbeNumber = materialDefault('transmissionDispersionAbbeNumber');
+    // Subsurface
+    /** Subsurface scattering weight. Default `0`. */
+    subsurfaceWeight = materialDefault('subsurfaceWeight');
+    /** Subsurface color. Default `[0.8, 0.8, 0.8]`. */
+    subsurfaceColor = materialDefault('subsurfaceColor');
+    /** Mean free path in scene units. Default `1`. */
+    subsurfaceRadius = materialDefault('subsurfaceRadius');
+    /** Per-channel multiplier of `subsurfaceRadius`. Default `[1, 0.5, 0.25]`. */
+    subsurfaceRadiusScale = materialDefault('subsurfaceRadiusScale');
+    /**
+     * Scattering anisotropy, -1 to 1. Default `0`.
+     * @deprecated Use subsurfaceScatterAnisotropy.
+     */
+    subsurfaceAnisotropy = materialDefault('subsurfaceAnisotropy');
+    // Fuzz (sheen)
+    /** Fuzz (sheen) layer weight. Default `0`. */
+    fuzzWeight = materialDefault('fuzzWeight');
+    /** Fuzz reflection color; substrate attenuation uses white fuzz albedo. Default `[1, 1, 1]`. */
+    fuzzColor = materialDefault('fuzzColor');
+    /** Fuzz roughness; imported from Three.js `sheenRoughness`. Default `0.5`. */
+    fuzzRoughness = materialDefault('fuzzRoughness');
+    // Coat
+    /** Clear coat weight. Default `0`. */
+    coatWeight = materialDefault('coatWeight');
+    /** Squared coat transmittance at normal incidence; colors the base and emission, not coat reflection. Default `[1, 1, 1]`. */
+    coatColor = materialDefault('coatColor');
+    /** Coat roughness. Default `0`. */
+    coatRoughness = materialDefault('coatRoughness');
+    /**
+     * OpenPBR GGX coat anisotropy, 0 to 1; uses the base geometry tangent. Default `0`.
+     * @deprecated Use coatRoughnessAnisotropy.
+     */
+    coatAnisotropy = materialDefault('coatAnisotropy');
+    /** Coat index of refraction. Default `1.6`. */
+    coatIor = materialDefault('coatIor');
+    /** Internal-reflection darkening: 0 compensates darkening, 1 is physical; absorption remains at 0. Default `1`. */
+    coatDarkening = materialDefault('coatDarkening');
+    // Thin film
+    /** Thin-film interference weight (iridescence). Default `0`. */
+    thinFilmWeight = materialDefault('thinFilmWeight');
+    /** Film thickness in micrometres; maximum endpoint when thinFilmMap is present. Default `0.5`. */
+    thinFilmThickness = materialDefault('thinFilmThickness');
+    /** Film index of refraction. Default `1.4`. */
+    thinFilmIor = materialDefault('thinFilmIor');
+    /** Thickness at a thinFilmMap sample of zero, in micrometres; ignored without a map. May exceed thinFilmThickness. Default `0`. */
+    thinFilmThicknessMinimum = materialDefault('thinFilmThicknessMinimum');
+    /** Linear channel sampled by thinFilmMap. Default `r`. */
+    thinFilmMapChannel = materialDefault('thinFilmMapChannel');
+    // Emission and geometry
+    /** Emission color. Default `[1, 1, 1]`. */
+    emissionColor = materialDefault('emissionColor');
+    /** Emitted radiance scale; `0` disables emission. Default `0`. */
+    emissionLuminance = materialDefault('emissionLuminance');
+    /**
+     * Coverage, `1` opaque. See `alphaMode`. Default `1`.
+     * @deprecated Use geometryOpacity.
+     */
+    opacity = materialDefault('opacity');
+    /**
+     * Treat the surface as an infinitely thin shell (leaves, paper). Default `false`.
+     * @deprecated Use geometryThinWalled.
+     */
+    thinWalled = materialDefault('thinWalled');
+    /** Disables geometric back-face culling and permits back-face emission. Default `false`. */
+    doubleSided = materialDefault('doubleSided');
+    // Textures
+    /** Base color texture, multiplied with `baseColor` using Texture color encoding. Default `undefined`. */
+    map;
+    /** Standalone opacity texture sampled from its green channel, matching Three.js. Default `undefined`. */
+    alphaMap;
+    /**
+     * Coverage for surface and shadow rays: `opaque` ignores alpha inputs,
+     * `mask` uses binary alpha testing, `blend` retains fractional coverage.
+     * `auto` derives the mode from the alpha inputs. Default `auto`.
+     */
+    alphaMode = materialDefault('alphaMode');
+    /** Alpha-test threshold for `mask` mode; equality is fully covered. Default `0`. */
+    alphaCutoff = materialDefault('alphaCutoff');
+    /** Emission texture multiplied with `emissionColor`. Default `undefined`. */
+    emissiveMap;
+    /** Tangent-space normal map. Default `undefined`. */
+    normalMap;
+    /** Normal map strength per axis. Default `[1, 1]`. */
+    normalScale = materialDefault('normalScale');
+    /** glTF-compatible B=metalness, G=specular roughness texture. Default `undefined`. */
+    metallicRoughnessMap;
+    /** Standalone roughness texture sampled from its green channel. Default `undefined`. */
+    roughnessMap;
+    /** Standalone metalness texture sampled from its blue channel. Default `undefined`. */
+    metalnessMap;
+    /** Multiplies transmission weight using the texture's red channel. Default `undefined`. */
+    transmissionMap;
+    /** Linear thickness-range texture; R and zero minimum preserve multiplication semantics. Default `undefined`. */
+    thinFilmMap;
+    /** Multiplies coatWeight by the linear red channel. Default `undefined`. */
+    coatWeightMap;
+    /** Multiplies coatRoughness by the linear green channel. Default `undefined`. */
+    coatRoughnessMap;
+    /** Multiplies fuzzColor by RGB channels using Texture color encoding. Default `undefined`. */
+    fuzzColorMap;
+    /** Multiplies fuzzRoughness by the linear alpha channel. Default `undefined`. */
+    fuzzRoughnessMap;
+    /** Multiplies specularWeight by the linear alpha channel. Default `undefined`. */
+    specularWeightMap;
+    /** Multiplies specularColor by RGB channels using Texture color encoding. Default `undefined`. */
+    specularColorMap;
+    /** Source convention for base specular anisotropy. `gltf` converts textured roughness and strength before coat roughening; `openpbr` uses native parameters. Default `openpbr`. */
+    specularAnisotropyModel = 'openpbr';
+    /** Linear RG tangent direction and B strength multiplier for the base specular layer. Default `undefined`. */
+    anisotropyMap;
+    /** Independent tangent-space coat normal in linear RGB. Without a map, coat uses the surface normal before base normal mapping. Default `undefined`. */
+    coatNormalMap;
+    /** XY strength of coatNormalMap; independent of normalScale. Default `[1, 1]`. */
+    coatNormalScale = materialDefault('coatNormalScale');
+    /** Base direction rotation in radians, counter-clockwise in tangent/bitangent space after RG decoding. Default `0`. */
+    specularAnisotropyRotation = 0;
+    /** Coat direction rotation in radians relative to the geometry tangent. Default `0`. */
+    coatAnisotropyRotation = 0;
+    /** GGX roughness anisotropy in [0, 1]; native OpenPBR or source glTF strength according to specularAnisotropyModel. Requires tangents. Default `0`. */
+    get specularRoughnessAnisotropy() { return this.specularAnisotropy; }
+    set specularRoughnessAnisotropy(value) { this.specularAnisotropy = value; }
+    /** OpenPBR coat GGX roughness anisotropy in [0, 1]. Default `0`. */
+    get coatRoughnessAnisotropy() { return this.coatAnisotropy; }
+    set coatRoughnessAnisotropy(value) { this.coatAnisotropy = value; }
+    /** Subsurface scattering anisotropy in [-1, 1]. Default `0`. */
+    get subsurfaceScatterAnisotropy() { return this.subsurfaceAnisotropy; }
+    set subsurfaceScatterAnisotropy(value) { this.subsurfaceAnisotropy = value; }
+    /** Surface coverage; alphaMode controls testing and blending. Default `1`. */
+    get geometryOpacity() { return this.opacity; }
+    set geometryOpacity(value) { this.opacity = value; }
+    /** Treat the surface as an infinitely thin shell. Default `false`. */
+    get geometryThinWalled() { return this.thinWalled; }
+    set geometryThinWalled(value) { this.thinWalled = value; }
+    // Renderer extensions
+    /**
+     * Invisible ground that only receives shadows, composited over the
+     * background. Default `false`.
+     */
+    shadowCatcher = materialDefault('shadowCatcher');
+    /** Displays emission without scattering or illuminating other surfaces. Default `false`. */
+    unlit = materialDefault('unlit');
+    /** Radius of rounded-edge shading (shader bevel) in scene units. `0` disables it. Default `0`. */
+    bevelSize = materialDefault('bevelSize');
+    /** How map alpha is used: ignored, opacity or transmission. Default `opaque`. */
+    mapAlphaUsage = materialDefault('mapAlphaUsage');
+    /** Procedural UV projection for textures without (good) UVs. Default `none`. */
+    uvProjection = materialDefault('uvProjection');
+    /** UV scale used with `uvProjection`. Default `[1, 1]`. */
+    uvProjectionScale = materialDefault('uvProjectionScale');
+    // Displacement
+    /** Height texture (red channel) for displacement. Default `undefined`. */
+    displacementMap;
+    /** Procedural UV projection for the displacement map. Default `none`. */
+    displacementUvProjection = materialDefault('displacementUvProjection');
+    /** UV scale used with `displacementUvProjection`. Default `1`. */
+    displacementUvProjectionScale = materialDefault('displacementUvProjectionScale');
+    /** Height multiplier in mesh-local coordinate units. Default `0.1`. */
+    displacementScale = materialDefault('displacementScale');
+    /** Offset added after scaling the height map, along the normal in mesh-local units; requires a displacement map. Default `0`. */
+    displacementBias = materialDefault('displacementBias');
+    /** Ray-marching step in mesh-local units; 0 automatically uses abs(displacementScale) / 32. Default `0`. */
+    displacementStepSize = materialDefault('displacementStepSize');
+}
+export { materialAlphaModeConstants } from '../renderer/materialConstants.js';
+export function resolveMaterialAlphaMode(material) {
+    if (material.alphaMode !== 'auto')
+        return material.alphaMode;
+    if (material.alphaCutoff > 0)
+        return 'mask';
+    if (material.opacity < 1 ||
+        material.mapAlphaUsage === "alpha" ||
+        material.alphaMap) {
+        return 'blend';
+    }
+    return 'opaque';
+}
+export { materialKeys, materialTextureKeys, materialGeometryKeys, materialParamKeys, getMaterialHashKey, resetMaterialTextureId } from './openPbrSchema.js';
+//# sourceMappingURL=MaterialState.js.map