@aura3d/rendering 3.0.1 → 4.0.2

package/dist/vfx/DecalBatch.js

@@ -0,0 +1,234 @@
+// PRD-07 P6-T1 — §6.9 DecalBatch: ring-allocated merged geometry per atlas
+// page × blend mode. The engine upserts decal nodes; the pass rebuilds one
+// dynamic vertex buffer per (page, blend) group and draws it once — decals
+// are no longer one draw each (E46). Capacity is the C-27 tier cap
+// (Low 64 / Medium 128 / High 256 / Ultra 512, replacing the hard-coded
+// AURA_DECAL_MAX_DECALS=32 under A3D_QR_VFX_DECALS); the ring evicts
+// oldest-first. Life/fade-out curves are evaluated on the CPU into the
+// vertex alpha at merge time (≤ 512 decals — trivial).
+/** C-27 decal capacity per tier (§6.9 — was a hard 32). */
+export const DECAL_TIER_CAP = { low: 64, medium: 128, high: 256, ultra: 512 };
+/** Decal vertex stride in floats: pos3 + normal3 + uv2 + color4 + fade4. */
+export const DECAL_VERTEX_FLOATS = 16;
+/** α at age `t` for the fade-in/hold/fade-out life curve. */
+export function decalLifeAlpha(slot, now) {
+    const age = now - slot.spawnTime;
+    if (!Number.isFinite(slot.life))
+        return 1;
+    if (age < 0 || age >= slot.life)
+        return 0;
+    const fadeIn = slot.fadeIn > 0 ? Math.min(1, age / slot.fadeIn) : 1;
+    const fadeOutStart = slot.life - slot.fadeOut;
+    const fadeOut = slot.fadeOut > 0 && age > fadeOutStart ? Math.max(0, (slot.life - age) / slot.fadeOut) : 1;
+    return fadeIn * fadeOut;
+}
+/**
+ * The merged decal ring. `upsert` inserts or replaces; on overflow the
+ * oldest-inserted slot evicts (oldest-first, §6.9). `buildAll` merges each
+ * (pageKey, blend) group into one interleaved buffer for a single draw.
+ */
+export class DecalBatch {
+    capacity;
+    slots = new Map(); // insertion order = ring order
+    spawns = new Map();
+    constructor(capacity) {
+        this.capacity = capacity;
+        if (!Number.isInteger(capacity) || capacity <= 0)
+            throw new Error("DecalBatch capacity must be a positive integer.");
+    }
+    get size() {
+        return this.slots.size;
+    }
+    /** Live slot ids — lets producers drop slots whose nodes left the scene. */
+    ids() {
+        return [...this.slots.keys()];
+    }
+    has(id) {
+        return this.slots.has(id);
+    }
+    /** True when the decal is present after upsert; evicted-oldest semantics. */
+    upsert(options, now) {
+        if (!this.spawns.has(options.id))
+            this.spawns.set(options.id, now);
+        if (!this.slots.has(options.id) && this.slots.size >= this.capacity) {
+            const oldest = this.slots.keys().next().value;
+            this.slots.delete(oldest);
+            this.spawns.delete(oldest);
+        }
+        const spawnTime = this.spawns.get(options.id) ?? now;
+        // Ring order = first-insertion order (Map.set on an existing key keeps its
+        // position), so a living decal's per-frame refresh never resets eviction.
+        this.slots.set(options.id, {
+            id: options.id,
+            pageKey: options.pageKey,
+            blend: options.blend ?? "alpha",
+            geometry: options.geometry,
+            color: options.color ?? [1, 1, 1, 1],
+            roughness: options.roughness ?? 0.5,
+            fade: {
+                angleStart: options.fade?.angleStart ?? 55,
+                angleEnd: options.fade?.angleEnd ?? 80,
+                near: options.fade?.near ?? 0,
+                far: options.fade?.far ?? Number.POSITIVE_INFINITY
+            },
+            polygonOffset: options.polygonOffset ?? { factor: -2, units: -2 },
+            spawnTime,
+            life: options.life ?? Number.POSITIVE_INFINITY,
+            fadeIn: options.fadeIn ?? 0,
+            fadeOut: options.fadeOut ?? 0
+        });
+        return true;
+    }
+    remove(id) {
+        this.slots.delete(id);
+        this.spawns.delete(id);
+    }
+    clear() {
+        this.slots.clear();
+        this.spawns.clear();
+    }
+    /** Age out expired decals, then merge each (page, blend) group. */
+    buildAll(now) {
+        for (const [id, slot] of this.slots) {
+            if (Number.isFinite(slot.life) && now - slot.spawnTime >= slot.life) {
+                this.slots.delete(id);
+                this.spawns.delete(id);
+            }
+        }
+        const groups = new Map();
+        for (const slot of this.slots.values()) {
+            const key = `${slot.pageKey}|${slot.blend}`;
+            let group = groups.get(key);
+            if (!group)
+                groups.set(key, (group = { blend: slot.blend, polygonOffset: slot.polygonOffset, items: [] }));
+            group.items.push(slot);
+        }
+        const out = [];
+        for (const [key, group] of groups) {
+            const pageKey = key.slice(0, key.indexOf("|"));
+            let totalVerts = 0;
+            let totalIdx = 0;
+            for (const slot of group.items) {
+                totalVerts += slot.geometry.vertices.length / (slot.geometry.stride ?? 8);
+                totalIdx += slot.geometry.indices.length;
+            }
+            const vertices = new Float32Array(totalVerts * DECAL_VERTEX_FLOATS);
+            const indices = new Uint32Array(totalIdx);
+            let vo = 0;
+            let io = 0;
+            let triangles = 0;
+            for (const slot of group.items) {
+                const alpha = decalLifeAlpha(slot, now) * slot.color[3];
+                const src = slot.geometry.vertices;
+                const stride = slot.geometry.stride ?? 8;
+                const vc = src.length / stride;
+                for (let v = 0; v < vc; v += 1) {
+                    const s = v * stride;
+                    const o = vo + v * DECAL_VERTEX_FLOATS;
+                    vertices[o + 0] = src[s + 0];
+                    vertices[o + 1] = src[s + 1];
+                    vertices[o + 2] = src[s + 2];
+                    vertices[o + 3] = src[s + 3];
+                    vertices[o + 4] = src[s + 4];
+                    vertices[o + 5] = src[s + 5];
+                    vertices[o + 6] = src[s + 6];
+                    vertices[o + 7] = src[s + 7];
+                    if (stride === 16) {
+                        // Fully baked vertices: keep color+fade, apply only the life alpha.
+                        vertices[o + 8] = src[s + 8];
+                        vertices[o + 9] = src[s + 9];
+                        vertices[o + 10] = src[s + 10];
+                        vertices[o + 11] = src[s + 11] * decalLifeAlpha(slot, now);
+                        vertices[o + 12] = src[s + 12];
+                        vertices[o + 13] = src[s + 13];
+                        vertices[o + 14] = src[s + 14];
+                        vertices[o + 15] = src[s + 15];
+                    }
+                    else {
+                        vertices[o + 8] = slot.color[0];
+                        vertices[o + 9] = slot.color[1];
+                        vertices[o + 10] = slot.color[2];
+                        vertices[o + 11] = alpha;
+                        vertices[o + 12] = slot.fade.angleStart;
+                        vertices[o + 13] = slot.fade.angleEnd;
+                        vertices[o + 14] = slot.fade.near;
+                        vertices[o + 15] = slot.fade.far;
+                    }
+                }
+                for (let i = 0; i < slot.geometry.indices.length; i += 1) {
+                    indices[io + i] = slot.geometry.indices[i] + vo / DECAL_VERTEX_FLOATS;
+                }
+                vo += vc * DECAL_VERTEX_FLOATS;
+                io += slot.geometry.indices.length;
+                triangles += slot.geometry.indices.length / 3;
+            }
+            out.push({
+                vertices,
+                indices,
+                vertexCount: totalVerts,
+                triangleCount: triangles,
+                pageKey,
+                blend: group.blend,
+                polygonOffset: group.polygonOffset
+            });
+        }
+        return out;
+    }
+}
+/**
+ * Flat-quad decal geometry for the common `decals.project` path: XZ ±0.5
+ * plane (facing +Y) transformed by quaternion `q` + `position`, lifted along
+ * the rotated +Y by `normalOffset`, UV [0,1]².
+ */
+export function decalQuadGeometry(q, position, size, normalOffset) {
+    const rot = (v) => {
+        const [x, y, z] = v;
+        const [qx, qy, qz, qw] = q;
+        // t = 2·q.xyz × v
+        const tx = 2 * (qy * z - qz * y);
+        const ty = 2 * (qz * x - qx * z);
+        const tz = 2 * (qx * y - qy * x);
+        return [
+            x + qw * tx + (qy * tz - qz * ty),
+            y + qw * ty + (qz * tx - qx * tz),
+            z + qw * tz + (qx * ty - qy * tx)
+        ];
+    };
+    const hw = size[0] * 0.5;
+    const hh = size[1] * 0.5;
+    const normal = rot([0, 1, 0]);
+    const verts = [];
+    const corners = [[-hw, -hh], [hw, -hh], [hw, hh], [-hw, hh]];
+    const uvs = [[0, 1], [1, 1], [1, 0], [0, 0]];
+    for (let i = 0; i < 4; i += 1) {
+        const local = rot([corners[i][0], normalOffset, corners[i][1]]);
+        verts.push(position[0] + local[0], position[1] + local[1], position[2] + local[2], normal[0], normal[1], normal[2], uvs[i][0], uvs[i][1]);
+    }
+    return {
+        vertices: new Float32Array(verts),
+        indices: new Uint32Array([0, 1, 2, 0, 2, 3])
+    };
+}
+/**
+ * §6.9/P6-T3 — convert a built surface-orientation ribbon strip (12-float
+ * layout: pos3+normal3+uv2+color4) into fully baked 16-float decal vertices:
+ * per-vertex color preserved, fade baked to "no fade" (angleEnd<=angleStart,
+ * far=+inf, disabled in the shader). Indices shared verbatim.
+ */
+export function ribbonStripToDecalGeometry(geometry) {
+    const src = geometry.vertices;
+    const vc = src.length / 12;
+    const vertices = new Float32Array(vc * DECAL_VERTEX_FLOATS);
+    for (let v = 0; v < vc; v += 1) {
+        const s = v * 12;
+        const o = v * DECAL_VERTEX_FLOATS;
+        for (let k = 0; k < 12; k += 1)
+            vertices[o + k] = src[s + k];
+        vertices[o + 12] = 0;
+        vertices[o + 13] = 0;
+        vertices[o + 14] = 0;
+        vertices[o + 15] = Number.POSITIVE_INFINITY;
+    }
+    return { vertices, indices: geometry.indices, stride: 16 };
+}
+//# sourceMappingURL=DecalBatch.js.map

package/dist/vfx/DecalBatch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DecalBatch.js","sourceRoot":"","sources":["../../../../../packages/rendering/src/vfx/DecalBatch.ts"],"names":[],"mappings":"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"}

package/dist/vfx/DecalPass.d.ts

@@ -0,0 +1,63 @@
+import type { RenderDevice, UniformValue } from "../RenderDevice.js";
+import type { FrameContributorContext } from "../contracts/frameGraph.js";
+import { VertexFormat } from "../VertexFormat.js";
+import { type DecalBatch } from "./DecalBatch.js";
+import type { Texture } from "../Texture.js";
+export declare const DECAL_VERTEX_FORMAT: VertexFormat;
+/** One punctual light for the decal BRDF (three.js MeshStandardMaterial parity). */
+export interface DecalLight {
+    readonly kind: "directional" | "point";
+    /** directional: unit vector TOWARD the light; point: world position. */
+    readonly vector: readonly [number, number, number];
+    /** colour × intensity (linear). */
+    readonly radiance: readonly [number, number, number];
+    /** point range cutoff (0 = none). */
+    readonly range?: number;
+}
+/** Per-frame scene lighting the decals shade with — the same lights as the surface below. */
+export interface DecalLighting {
+    readonly lights: readonly DecalLight[];
+    /** Ambient colour × intensity; the shader applies BRDF_Lambert (1/π). */
+    readonly ambient: readonly [number, number, number];
+}
+export declare const DECAL_MAX_LIGHTS = 5;
+/** Pack ≤4 lights into the u_lightVector / u_lightRadiance arrays. */
+export declare function packDecalLighting(lighting: DecalLighting): {
+    vector: Float32Array;
+    radiance: Float32Array;
+    count: number;
+};
+/** Optional texture lookup for page keys — the engine resolves URLs/pages. */
+export type DecalTextureResolver = (pageKey: string) => Texture | null;
+export interface DecalPassOptions {
+    readonly resolveTexture?: DecalTextureResolver;
+    /** Sun light for the §8.8 lobe — defaults are sane for tests. */
+    readonly sunDirection?: readonly [number, number, number];
+    readonly sunColor?: readonly [number, number, number];
+    readonly roughness?: number;
+    /** Scene lights for the decal BRDF; null/absent → DEFAULT_DECAL_LIGHTING. */
+    readonly lighting?: (ctx: FrameContributorContext) => DecalLighting | null;
+    readonly fog?: boolean;
+    /** §8.4 packed uniforms when `fog` is set (from the prd07.fog blackboard). */
+    readonly fogUniforms?: (ctx: FrameContributorContext) => Map<string, UniformValue> | null;
+    /** Reported once per page key when multiply emulates alpha-over. */
+    readonly onNote?: (code: string, message: string) => void;
+}
+export declare class DecalPass {
+    private readonly device;
+    private readonly options;
+    private readonly programs;
+    private vertexBuffer;
+    private indexBuffer;
+    private vertexCapacity;
+    private indexCapacity;
+    private readonly blendFallbackNoted;
+    constructor(device: RenderDevice, options?: DecalPassOptions);
+    /** Draws every populated (page, blend) group — one draw each. Returns draw count for tests/diagnostics. */
+    draw(batch: DecalBatch, ctx: FrameContributorContext, now: number): number;
+    private drawGeometry;
+    private ensureBuffer;
+    private program;
+    dispose(): void;
+}
+//# sourceMappingURL=DecalPass.d.ts.map

package/dist/vfx/DecalPass.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DecalPass.d.ts","sourceRoot":"","sources":["../../../../../packages/rendering/src/vfx/DecalPass.ts"],"names":[],"mappings":"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"}

package/dist/vfx/DecalPass.js

@@ -0,0 +1,159 @@
+// PRD-07 P6-T1 — §6.9 decal draw pass. Runs in the `after-opaque` phase
+// (before transparents): one indexed draw per atlas page × blend group from
+// DecalBatch.buildAll. Lit per §8.8; blend is `alpha` for marks and
+// `multiply` for grime — under the C-04 stub multiply is emulated as
+// alpha-over with black at 1 − luminance and reported once per page key as
+// VFX_BLEND_FALLBACK.
+import { TextureBinding } from "../TextureBinding.js";
+import { VertexFormat } from "../VertexFormat.js";
+import { DECAL_VERTEX_FLOATS } from "./DecalBatch.js";
+import { DECAL_SHADER_MARKER, decalFragmentSource, decalProgramKey, decalVertexSource } from "./shaders/decal.glsl.js";
+export const DECAL_VERTEX_FORMAT = new VertexFormat([
+    { semantic: "position", components: 3, offset: 0, shaderName: "a_position" },
+    { semantic: "normal", components: 3, offset: 12, shaderName: "a_normal" },
+    { semantic: "uv", components: 2, offset: 24, shaderName: "a_uv" },
+    { semantic: "color", components: 4, offset: 32, shaderName: "a_color" },
+    // `uv1` = extra per-vertex channel; bound to a_fade by name (angleStart, angleEnd, nearFade, farFade).
+    { semantic: "uv1", components: 4, offset: 48, shaderName: "a_fade" }
+], DECAL_VERTEX_FLOATS * 4);
+// 5, not 4: the WebGL2 binder uploads any 16-float array as a mat4
+// (uniformMatrix4fv), so a vec4[4] array raised GL_INVALID_OPERATION (0x502).
+export const DECAL_MAX_LIGHTS = 5;
+/** Pack ≤4 lights into the u_lightVector / u_lightRadiance arrays. */
+export function packDecalLighting(lighting) {
+    const vector = new Float32Array(DECAL_MAX_LIGHTS * 4);
+    const radiance = new Float32Array(DECAL_MAX_LIGHTS * 4);
+    const count = Math.min(DECAL_MAX_LIGHTS, lighting.lights.length);
+    for (let i = 0; i < count; i++) {
+        const light = lighting.lights[i];
+        vector.set([light.vector[0], light.vector[1], light.vector[2], light.kind === "point" ? 1 : 0], i * 4);
+        radiance.set([light.radiance[0], light.radiance[1], light.radiance[2], light.range ?? 0], i * 4);
+    }
+    return { vector, radiance, count };
+}
+/** Fallback when no scene lighting is published: one soft key + dim ambient. */
+const DEFAULT_DECAL_LIGHTING = {
+    lights: [{ kind: "directional", vector: [0.5, 0.8, 0.3], radiance: [1, 1, 1] }],
+    ambient: [0.3, 0.3, 0.33]
+};
+export class DecalPass {
+    device;
+    options;
+    programs = new Map();
+    vertexBuffer = null;
+    indexBuffer = null;
+    vertexCapacity = 0;
+    indexCapacity = 0;
+    blendFallbackNoted = new Set();
+    constructor(device, options = {}) {
+        this.device = device;
+        this.options = options;
+    }
+    /** Draws every populated (page, blend) group — one draw each. Returns draw count for tests/diagnostics. */
+    draw(batch, ctx, now) {
+        const geometries = batch.buildAll(now);
+        for (const geometry of geometries)
+            this.drawGeometry(geometry, ctx);
+        return geometries.length;
+    }
+    drawGeometry(geometry, ctx) {
+        const vb = this.ensureBuffer("vertex", geometry.vertices.byteLength, "vb");
+        this.device.updateBuffer(vb, 0, geometry.vertices);
+        const ib = this.ensureBuffer("index", geometry.indices.byteLength, "ib");
+        this.device.updateBuffer(ib, 0, geometry.indices);
+        const texture = this.options.resolveTexture?.(geometry.pageKey) ?? null;
+        const defines = {
+            albedoTexture: texture !== null,
+            normalTexture: false,
+            multiply: geometry.blend === "multiply",
+            fog: this.options.fog === true
+        };
+        if (defines.multiply && !this.blendFallbackNoted.has(geometry.pageKey)) {
+            this.blendFallbackNoted.add(geometry.pageKey);
+            this.options.onNote?.("VFX_BLEND_FALLBACK", `prd07.decals: multiply blend emulated as alpha-over (black at 1−luminance) for page "${geometry.pageKey}" under the C-04 stub`);
+        }
+        const sceneLighting = this.options.lighting?.(ctx) ?? DEFAULT_DECAL_LIGHTING;
+        const lighting = packDecalLighting(sceneLighting);
+        const ambient = sceneLighting.ambient;
+        const uniforms = new Map([
+            ["u_viewProjection", ctx.camera?.viewProjectionMatrix ?? IDENTITY_MAT4],
+            // Fog-chunk inscatter inputs (the decal BRDF reads u_light* below).
+            ["u_sunDirection", [...(this.options.sunDirection ?? [0.5, 0.8, 0.3])]],
+            ["u_sunColor", [...(this.options.sunColor ?? [1, 1, 1])]],
+            ["u_roughness", this.options.roughness ?? 0.5],
+            ["u_lightVector", lighting.vector],
+            ["u_lightRadiance", lighting.radiance],
+            ["u_lightCount", lighting.count],
+            ["u_ambientIrradiance", [ambient[0], ambient[1], ambient[2]]],
+            ["u_cameraPosition", [...(ctx.camera?.position ?? [0, 0, 0])]]
+        ]);
+        if (texture)
+            uniforms.set("u_albedo", new TextureBinding({ name: "u_albedo", texture }));
+        if (defines.fog) {
+            const extra = this.options.fogUniforms?.(ctx);
+            if (extra)
+                for (const [k, v] of extra)
+                    uniforms.set(k, v);
+        }
+        this.device.draw({
+            label: `prd07.decals.${geometry.pageKey}.${geometry.blend}`,
+            topology: "triangles",
+            vertexBuffer: vb,
+            vertexFormat: DECAL_VERTEX_FORMAT,
+            vertexCount: geometry.vertexCount,
+            indexBuffer: ib,
+            indexType: "uint32",
+            indexCount: geometry.indices.length,
+            shader: this.program(defines),
+            uniforms,
+            renderState: {
+                depthTest: true,
+                depthWrite: false,
+                cullMode: "none",
+                blend: true,
+                blendMode: "alpha",
+                depthCompare: "less-equal",
+                ...(geometry.polygonOffset ? { polygonOffset: geometry.polygonOffset } : {})
+            }
+        });
+    }
+    ensureBuffer(usage, bytes, which) {
+        const capacity = which === "vb" ? this.vertexCapacity : this.indexCapacity;
+        const existing = which === "vb" ? this.vertexBuffer : this.indexBuffer;
+        if (existing && capacity >= bytes)
+            return existing;
+        const next = Math.max(bytes, capacity * 2 || 0, 4096);
+        existing?.dispose();
+        const buffer = this.device.createBuffer(usage, next);
+        if (which === "vb") {
+            this.vertexBuffer = buffer;
+            this.vertexCapacity = next;
+        }
+        else {
+            this.indexBuffer = buffer;
+            this.indexCapacity = next;
+        }
+        return buffer;
+    }
+    program(defines) {
+        const key = decalProgramKey(defines);
+        let shader = this.programs.get(key);
+        if (!shader) {
+            shader = this.device.createShaderProgram({
+                label: key,
+                vertex: decalVertexSource(),
+                fragment: decalFragmentSource(defines),
+                marker: DECAL_SHADER_MARKER
+            });
+            this.programs.set(key, shader);
+        }
+        return shader;
+    }
+    dispose() {
+        this.vertexBuffer?.dispose();
+        this.indexBuffer?.dispose();
+        this.programs.clear();
+    }
+}
+const IDENTITY_MAT4 = new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]);
+//# sourceMappingURL=DecalPass.js.map

package/dist/vfx/DecalPass.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DecalPass.js","sourceRoot":"","sources":["../../../../../packages/rendering/src/vfx/DecalPass.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,4EAA4E;AAC5E,oEAAoE;AACpE,qEAAqE;AACrE,2EAA2E;AAC3E,sBAAsB;AAItB,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAAE,mBAAmB,EAAuC,MAAM,cAAc,CAAC;AACxF,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,eAAe,EAAE,iBAAiB,EAA4B,MAAM,sBAAsB,CAAC;AAG9I,MAAM,CAAC,MAAM,mBAAmB,GAAG,IAAI,YAAY,CACjD;IACE,EAAE,QAAQ,EAAE,UAAU,EAAE,UAAU,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,UAAU,EAAE,YAAY,EAAE;IAC5E,EAAE,QAAQ,EAAE,QAAQ,EAAE,UAAU,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,UAAU,EAAE,UAAU,EAAE;IACzE,EAAE,QAAQ,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,UAAU,EAAE,MAAM,EAAE;IACjE,EAAE,QAAQ,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,UAAU,EAAE,SAAS,EAAE;IACvE,uGAAuG;IACvG,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,UAAU,EAAE,QAAQ,EAAE;CACrE,EACD,mBAAmB,GAAG,CAAC,CACxB,CAAC;AAoBF,mEAAmE;AACnE,8EAA8E;AAC9E,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC;AAElC,sEAAsE;AACtE,MAAM,UAAU,iBAAiB,CAAC,QAAuB;IACvD,MAAM,MAAM,GAAG,IAAI,YAAY,CAAC,gBAAgB,GAAG,CAAC,CAAC,CAAC;IACtD,MAAM,QAAQ,GAAG,IAAI,YAAY,CAAC,gBAAgB,GAAG,CAAC,CAAC,CAAC;IACxD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,gBAAgB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACjE,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC;QAC/B,MAAM,KAAK,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAE,CAAC;QAClC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;QACvG,QAAQ,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,KAAK,IAAI,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACnG,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;AACrC,CAAC;AAED,gFAAgF;AAChF,MAAM,sBAAsB,GAAkB;IAC5C,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;IAC/E,OAAO,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC;CAC1B,CAAC;AAoBF,MAAM,OAAO,SAAS;IASD;IACA;IATF,QAAQ,GAAG,IAAI,GAAG,EAA+B,CAAC;IAC3D,YAAY,GAAwB,IAAI,CAAC;IACzC,WAAW,GAAwB,IAAI,CAAC;IACxC,cAAc,GAAG,CAAC,CAAC;IACnB,aAAa,GAAG,CAAC,CAAC;IACT,kBAAkB,GAAG,IAAI,GAAG,EAAU,CAAC;IAExD,YACmB,MAAoB,EACpB,UAA4B,EAAE;QAD9B,WAAM,GAAN,MAAM,CAAc;QACpB,YAAO,GAAP,OAAO,CAAuB;IAC9C,CAAC;IAEJ,2GAA2G;IAC3G,IAAI,CAAC,KAAiB,EAAE,GAA4B,EAAE,GAAW;QAC/D,MAAM,UAAU,GAAG,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;QACvC,KAAK,MAAM,QAAQ,IAAI,UAAU;YAAE,IAAI,CAAC,YAAY,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;QACpE,OAAO,UAAU,CAAC,MAAM,CAAC;IAC3B,CAAC;IAEO,YAAY,CAAC,QAAuB,EAAE,GAA4B;QACxE,MAAM,EAAE,GAAG,IAAI,CAAC,YAAY,CAAC,QAAQ,EAAE,QAAQ,CAAC,QAAQ,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;QAC3E,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,EAAE,EAAE,CAAC,EAAE,QAAQ,CAAC,QAAQ,CAAC,CAAC;QACnD,MAAM,EAAE,GAAG,IAAI,CAAC,YAAY,CAAC,OAAO,EAAE,QAAQ,CAAC,OAAO,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;QACzE,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,EAAE,EAAE,CAAC,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC;QAElD,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,cAAc,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC;QACxE,MAAM,OAAO,GAAwB;YACnC,aAAa,EAAE,OAAO,KAAK,IAAI;YAC/B,aAAa,EAAE,KAAK;YACpB,QAAQ,EAAE,QAAQ,CAAC,KAAK,KAAK,UAAU;YACvC,GAAG,EAAE,IAAI,CAAC,OAAO,CAAC,GAAG,KAAK,IAAI;SAC/B,CAAC;QACF,IAAI,OAAO,CAAC,QAAQ,IAAI,CAAC,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;YACvE,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;YAC9C,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CACnB,oBAAoB,EACpB,wFAAwF,QAAQ,CAAC,OAAO,uBAAuB,CAChI,CAAC;QACJ,CAAC;QACD,MAAM,aAAa,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,IAAI,sBAAsB,CAAC;QAC7E,MAAM,QAAQ,GAAG,iBAAiB,CAAC,aAAa,CAAC,CAAC;QAClD,MAAM,OAAO,GAAG,aAAa,CAAC,OAAO,CAAC;QACtC,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAuB;YAC7C,CAAC,kBAAkB,EAAE,GAAG,CAAC,MAAM,EAAE,oBAAoB,IAAI,aAAa,CAAC;YACvE,oEAAoE;YACpE,CAAC,gBAAgB,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,YAAY,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC;YACvE,CAAC,YAAY,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;YACzD,CAAC,aAAa,EAAE,IAAI,CAAC,OAAO,CAAC,SAAS,IAAI,GAAG,CAAC;YAC9C,CAAC,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC;YAClC,CAAC,iBAAiB,EAAE,QAAQ,CAAC,QAAQ,CAAC;YACtC,CAAC,cAAc,EAAE,QAAQ,CAAC,KAAK,CAAC;YAChC,CAAC,qBAAqB,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;YAC7D,CAAC,kBAAkB,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,EAAE,QAAQ,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;SAC/D,CAAC,CAAC;QACH,IAAI,OAAO;YAAE,QAAQ,CAAC,GAAG,CAAC,UAAU,EAAE,IAAI,cAAc,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC;QACzF,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;YAChB,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,GAAG,CAAC,CAAC;YAC9C,IAAI,KAAK;gBAAE,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,KAAK;oBAAE,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QAC5D,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;YACf,KAAK,EAAE,gBAAgB,QAAQ,CAAC,OAAO,IAAI,QAAQ,CAAC,KAAK,EAAE;YAC3D,QAAQ,EAAE,WAAW;YACrB,YAAY,EAAE,EAAE;YAChB,YAAY,EAAE,mBAAmB;YACjC,WAAW,EAAE,QAAQ,CAAC,WAAW;YACjC,WAAW,EAAE,EAAE;YACf,SAAS,EAAE,QAAQ;YACnB,UAAU,EAAE,QAAQ,CAAC,OAAO,CAAC,MAAM;YACnC,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC;YAC7B,QAAQ;YACR,WAAW,EAAE;gBACX,SAAS,EAAE,IAAI;gBACf,UAAU,EAAE,KAAK;gBACjB,QAAQ,EAAE,MAAM;gBAChB,KAAK,EAAE,IAAI;gBACX,SAAS,EAAE,OAAO;gBAClB,YAAY,EAAE,YAAY;gBAC1B,GAAG,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,QAAQ,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAC7E;SACF,CAAC,CAAC;IACL,CAAC;IAEO,YAAY,CAAC,KAAyB,EAAE,KAAa,EAAE,KAAkB;QAC/E,MAAM,QAAQ,GAAG,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC;QAC3E,MAAM,QAAQ,GAAG,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC;QACvE,IAAI,QAAQ,IAAI,QAAQ,IAAI,KAAK;YAAE,OAAO,QAAQ,CAAC;QACnD,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,QAAQ,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC;QACtD,QAAQ,EAAE,OAAO,EAAE,CAAC;QACpB,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QACrD,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;YACnB,IAAI,CAAC,YAAY,GAAG,MAAM,CAAC;YAC3B,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC;QAC7B,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,WAAW,GAAG,MAAM,CAAC;YAC1B,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC;QAC5B,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAEO,OAAO,CAAC,OAA4B;QAC1C,MAAM,GAAG,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;QACrC,IAAI,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACpC,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,mBAAmB,CAAC;gBACvC,KAAK,EAAE,GAAG;gBACV,MAAM,EAAE,iBAAiB,EAAE;gBAC3B,QAAQ,EAAE,mBAAmB,CAAC,OAAO,CAAC;gBACtC,MAAM,EAAE,mBAAmB;aAC5B,CAAC,CAAC;YACH,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QACjC,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,OAAO;QACL,IAAI,CAAC,YAAY,EAAE,OAAO,EAAE,CAAC;QAC7B,IAAI,CAAC,WAAW,EAAE,OAAO,EAAE,CAAC;QAC5B,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;IACxB,CAAC;CACF;AAED,MAAM,aAAa,GAAG,IAAI,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC"}

package/dist/vfx/LowResParticles.d.ts

@@ -0,0 +1,31 @@
+import type { RenderDevice, RenderTarget } from "../RenderDevice.js";
+import type { AuraQualityTierSettings } from "../contracts/quality.js";
+import { QUALITY_TIERS } from "../contracts/quality.js";
+import type { ResolvedSceneDepth } from "./SceneDepthAdapter.js";
+/** §6.2 particle GPU budget per tier (ms). Custom tier settings fall back to
+ *  matching by `particleBudget`, then to the `high` budget. */
+export declare const PARTICLE_GPU_BUDGET_MS: Record<keyof typeof QUALITY_TIERS | "default", number>;
+export declare function particleGpuBudgetMs(tier: AuraQualityTierSettings): number;
+/** EWMA auto-enable policy: on above the budget, off below 75% of it. */
+export declare class LowResAutoBudget {
+    private readonly hysteresis;
+    private ewma;
+    private frames;
+    constructor(hysteresis?: number);
+    /** Feed one measured particle-GPU-ms sample; returns whether low-res is on. */
+    note(ms: number, budgetMs: number, enabled: boolean): boolean;
+    reset(): void;
+}
+export declare class LowResParticleTarget {
+    private readonly device;
+    private target;
+    private fullscreenBuffer;
+    private readonly programs;
+    constructor(device: RenderDevice);
+    /** Half-res RGBA8 target sized to the frame; recreated on resize. */
+    acquire(frameWidth: number, frameHeight: number): RenderTarget;
+    /** Fullscreen upsample into whichever target is currently bound. */
+    composite(depth: ResolvedSceneDepth | null): void;
+    dispose(): void;
+}
+//# sourceMappingURL=LowResParticles.d.ts.map

package/dist/vfx/LowResParticles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LowResParticles.d.ts","sourceRoot":"","sources":["../../../../../packages/rendering/src/vfx/LowResParticles.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAgB,YAAY,EAAE,YAAY,EAA0B,MAAM,iBAAiB,CAAC;AACxG,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AACpE,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAYrD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAE9D;+DAC+D;AAC/D,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,MAAM,OAAO,aAAa,GAAG,SAAS,EAAE,MAAM,CAMzF,CAAC;AAEF,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,uBAAuB,GAAG,MAAM,CAQzE;AAID,yEAAyE;AACzE,qBAAa,gBAAgB;IAIf,OAAO,CAAC,QAAQ,CAAC,UAAU;IAHvC,OAAO,CAAC,IAAI,CAAK;IACjB,OAAO,CAAC,MAAM,CAAK;gBAEU,UAAU,SAAO;IAE9C,+EAA+E;IAC/E,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO;IAS7D,KAAK,IAAI,IAAI;CAId;AAED,qBAAa,oBAAoB;IAKnB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAJnC,OAAO,CAAC,MAAM,CAA6B;IAC3C,OAAO,CAAC,gBAAgB,CAA6B;IACrD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAoE;gBAEhE,MAAM,EAAE,YAAY;IAEjD,qEAAqE;IACrE,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,YAAY;IAkB9D,oEAAoE;IACpE,SAAS,CAAC,KAAK,EAAE,kBAAkB,GAAG,IAAI,GAAG,IAAI;IA+CjD,OAAO,IAAI,IAAI;CAQhB"}