@aura3d/rendering 3.0.1 → 4.0.2

package/dist/renderer/Background.js

@@ -0,0 +1,259 @@
+// PR 0b-2 carve-out (CONTRACTS.md §3.3) — verbatim move from Renderer.ts; 0 changed logic lines.
+// File: packages/rendering/src/renderer/Background.ts — owner lane 02.
+import { TextureBinding } from "../TextureBinding.js";
+import { Sampler } from "../Sampler.js";
+import { buildNeutralRoomLegacyProbe, probeToEquirectTexture } from "../environment/probeBuild.js";
+import { isIterable } from "./RenderShared.js";
+import { Scene } from "@aura3d/scene";
+import { rendererQrFlags } from "./FrameGraph.js";
+import { readPrd02KillSwitches } from "../passes/Prd02SubFlags.js";
+/** Specular-cube background binding uses the mip chain (PRD-02 §8.7 blurriness→lod). */
+const PRD02_BACKGROUND_SAMPLER = new Sampler({
+    minFilter: "linear-mipmap-linear",
+    magFilter: "linear",
+    addressU: "clamp-to-edge",
+    addressV: "clamp-to-edge"
+});
+export function collectEnvironmentBackground(source) {
+    if (source instanceof Scene || isIterable(source) || source.environmentBackground === false)
+        return undefined;
+    if (rendererQrFlags().on("A3D_QR_LIGHTING")) {
+        // `?a3dLighting=background=off` → fall through to the authored
+        // environmentBackground (§6.5 kill switch, §17 toggle-delta).
+        if (!readPrd02KillSwitches(source).background)
+            return source.environmentBackground;
+        const resolved = resolvePrd02EnvironmentBackground(source);
+        if (resolved)
+            return resolved;
+    }
+    return source.environmentBackground;
+}
+/**
+ * prd02.background contributor (PRD-02 §9): the active C-09 probe supplies the
+ * background — its equirect `background` texture when one exists and
+ * `blurriness == 0`, otherwise the specular cube at lod = roughnessToLod(blur).
+ * `environmentBackground: false` keeps the solid colour (returns undefined).
+ */
+export function resolvePrd02EnvironmentBackground(source) {
+    const probe = source.environmentProbe;
+    if (!probe)
+        return undefined;
+    // A probe bound only for IBL (neutral-room floor, `background: false`)
+    // keeps the authored solid/sky background instead of painting the room.
+    if (source.environmentProbeBackground === false)
+        return undefined;
+    const explicit = source.environmentBackground;
+    const blurriness = source.backgroundBlurriness
+        ?? (typeof explicit === "object" ? explicit.blurriness : 0)
+        ?? 0;
+    // E3 parity gap (conjunction only): an HDRI probe's `background` is the
+    // raw rgba32f decode intermediate (GPUPMREMGenerator.fromEquirect). RGBA32F
+    // is not linear-filterable in core WebGL2 (OES_texture_float_linear), and
+    // the binding below carries the default LINEAR sampler — a sampler object
+    // overrides the upload path's NEAREST pin, so the texture is incomplete
+    // and samples (0,0,0,1): L4 runs 38429097048/38429102473 measured pure
+    // black backgrounds on the HDRI scenes while the rgba16f specular cube
+    // shaded the objects correctly in the same frames. Under the conjunction,
+    // fall through to that filterable mipmapped cube instead of binding the
+    // 32f equirect. Conjunction-off binds stay byte-identical; follow-up:
+    // give the factory a half-float equirect background and drop this gate.
+    const equirectFilterable = probe.background?.format !== "rgba32f";
+    const e3Conjunction = rendererQrFlags().on("A3D_QR_COMPILER") && rendererQrFlags().on("A3D_QR_LIGHTING");
+    if (probe.background && blurriness === 0 && !(e3Conjunction && !equirectFilterable)) {
+        return {
+            projection: "equirect",
+            texture: new TextureBinding({ name: "u_environmentBackgroundTexture", texture: probe.background, required: true }),
+            intensity: typeof explicit === "object" ? explicit.intensity : 1,
+            rotation: typeof explicit === "object" ? explicit.rotation : 0,
+            inverseViewProjectionMatrix: typeof explicit === "object" ? explicit.inverseViewProjectionMatrix : undefined
+        };
+    }
+    return {
+        projection: "cubemap",
+        texture: new TextureBinding({
+            name: "u_environmentBackgroundCubeTexture",
+            texture: probe.specularCube,
+            required: true,
+            sampler: PRD02_BACKGROUND_SAMPLER
+        }),
+        intensity: typeof explicit === "object" ? explicit.intensity : 1,
+        rotation: typeof explicit === "object" ? explicit.rotation : 0,
+        blurriness,
+        mipCount: probe.mipCount,
+        inverseViewProjectionMatrix: typeof explicit === "object" ? explicit.inverseViewProjectionMatrix : undefined
+    };
+}
+export function collectEnvironmentLighting(source) {
+    if (source instanceof Scene || isIterable(source))
+        return undefined;
+    if (source.environmentLighting === false)
+        return cloneEnvironmentLighting(DISABLED_RENDERER_ENVIRONMENT_LIGHTING);
+    if (rendererQrFlags().on("A3D_QR_LIGHTING")) {
+        const probeLighting = resolvePrd02EnvironmentLighting(source);
+        if (probeLighting)
+            return probeLighting;
+        // #1141 / 02-S2: without A3D_QR_COMPILER no C-09 probe is ever bound
+        // (only compileScene binds one), so the legacy bridge's environment —
+        // the category generated map or the authored-ambient-only branch — was
+        // all that lit a scene once the fallback rig is gone. Under the flag the
+        // neutral room replaces those fallbacks (C-09 `prd02.neutral-room`);
+        // authored environments keep their lighting, authored ambient stays additive.
+        if (isPrd02LegacyFallbackEnvironment(source.environmentLighting))
+            return resolvePrd02NeutralRoomLighting(source.environmentLighting);
+    }
+    if (source.environmentLighting)
+        return source.environmentLighting;
+    return cloneEnvironmentLighting(DEFAULT_RENDERER_ENVIRONMENT_LIGHTING);
+}
+/** Same process-global registry `compiler/environment.ts` fills (Symbol.for: survives duplicated module instances). */
+const PRD02_LEGACY_FALLBACK_ENVIRONMENTS = Symbol.for("aura3d.prd02.legacyFallbackEnvironments");
+/**
+ * True when the source has no environment at all, or the engine marked it as
+ * the legacy fallback of a scene with no environment and no lights (the
+ * scene-category generated map). Authored environments and scenes with
+ * authored lights are never marked and keep their lighting.
+ */
+export function isPrd02LegacyFallbackEnvironment(lighting) {
+    if (!lighting)
+        return true;
+    const store = globalThis;
+    return store[PRD02_LEGACY_FALLBACK_ENVIRONMENTS]?.has(lighting) ?? false;
+}
+/** One directional neutral room per renderer process (analytic r185 room + SH9 irradiance last level; no GGX prefilter). */
+let prd02NeutralFloor = null;
+/**
+ * Neutral-room lighting replacing a legacy fallback environment. The
+ * authored-ambient branch (a constant colour, no map, no procedural sky)
+ * keeps its colour and intensity as the additive ambient term; the
+ * scene-category generated map is dropped entirely (PRD-02 R16: no category
+ * heuristics under the flag).
+ */
+export function resolvePrd02NeutralRoomLighting(legacy) {
+    prd02NeutralFloor ??= buildNeutralRoomLegacyProbe();
+    const ambientOnly = legacy && !legacy.proceduralMap && !legacy.environmentMapTexture && !legacy.environmentCubeMapTexture;
+    const ambient = ambientOnly && legacy.intensity > 0
+        ? { color: [legacy.color[0], legacy.color[1], legacy.color[2]], intensity: legacy.intensity }
+        : null;
+    const probeSource = { environmentProbe: prd02NeutralFloor, environmentProbeAmbient: ambient };
+    return resolvePrd02EnvironmentLighting(probeSource);
+}
+/** One mipped rgba16f equirect per bound probe (WeakMap; disposed with the probe's specular cube). */
+const prd02ProbeEquirects = new WeakMap();
+/**
+ * PRD-02 Phase 3 legacy bridge: when a C-09 probe is bound, the legacy
+ * environment-lighting path samples a *linear HDR* mipped equirect — no
+ * Reinhard, no RGBA8 (E5 fix). The legacy procedural map is dropped.
+ */
+export function resolvePrd02EnvironmentLighting(source) {
+    const probe = source.environmentProbe;
+    if (!probe)
+        return undefined;
+    let equirect = prd02ProbeEquirects.get(probe);
+    if (!equirect) {
+        equirect = probeToEquirectTexture(probe);
+        prd02ProbeEquirects.set(probe, equirect);
+    }
+    const meta = source;
+    const diffuse = meta.environmentProbeDiffuseIntensity ?? 1;
+    const specular = meta.environmentProbeSpecularIntensity ?? 1;
+    const ambient = meta.environmentProbeAmbient ?? null;
+    return {
+        color: ambient?.color ?? [1, 1, 1],
+        intensity: ambient?.intensity ?? 0,
+        environmentMapTexture: new TextureBinding({
+            name: "u_environmentMapTexture",
+            texture: equirect,
+            required: true,
+            expectedColorSpace: "linear",
+            sampler: new Sampler({ minFilter: "linear-mipmap-linear", magFilter: "linear", addressU: "repeat", addressV: "clamp-to-edge" })
+        }),
+        environmentCubeMapTexture: new TextureBinding({
+            name: "u_environmentCubeMapTexture",
+            texture: probe.specularCube,
+            required: false,
+            expectedColorSpace: "linear",
+            sampler: PRD02_BACKGROUND_SAMPLER
+        }),
+        environmentMapIntensity: diffuse,
+        environmentMapSpecularIntensity: specular,
+        environmentMapMipCount: equirect.mipLevels.length,
+        environmentMapEncoding: "linear",
+        // E3 stage-2b: carry the probe itself (cube + SH9) to ForwardPass for
+        // the PRD-02 IBL pack. Attached only under the conjunction so the
+        // LIGHTING-only lighting object stays byte-identical.
+        ...(rendererQrFlags().on("A3D_QR_COMPILER") && rendererQrFlags().on("A3D_QR_LIGHTING")
+            ? { environmentProbe: probe }
+            : {})
+    };
+}
+export function collectEnvironmentFog(source) {
+    if (source instanceof Scene || isIterable(source))
+        return undefined;
+    return source.environmentFog;
+}
+function cloneEnvironmentLighting(environment) {
+    return {
+        color: [...environment.color],
+        intensity: environment.intensity,
+        ...(environment.proceduralMap
+            ? {
+                proceduralMap: {
+                    skyColor: [...environment.proceduralMap.skyColor],
+                    horizonColor: [...environment.proceduralMap.horizonColor],
+                    groundColor: [...environment.proceduralMap.groundColor],
+                    specularColor: [...environment.proceduralMap.specularColor],
+                    intensity: environment.proceduralMap.intensity,
+                    specularIntensity: environment.proceduralMap.specularIntensity
+                }
+            }
+            : {}),
+        ...(environment.environmentMapTexture ? { environmentMapTexture: environment.environmentMapTexture } : {}),
+        ...(environment.environmentCubeMapTexture ? { environmentCubeMapTexture: environment.environmentCubeMapTexture } : {}),
+        ...(environment.environmentMapIntensity !== undefined ? { environmentMapIntensity: environment.environmentMapIntensity } : {}),
+        ...(environment.environmentMapSpecularIntensity !== undefined ? { environmentMapSpecularIntensity: environment.environmentMapSpecularIntensity } : {}),
+        ...(environment.environmentMapRotation !== undefined ? { environmentMapRotation: environment.environmentMapRotation } : {}),
+        ...(environment.environmentMapMipCount !== undefined ? { environmentMapMipCount: environment.environmentMapMipCount } : {}),
+        ...(environment.environmentMapEncoding ? { environmentMapEncoding: environment.environmentMapEncoding } : {}),
+        ...(environment.environmentBrdfLutTexture ? { environmentBrdfLutTexture: environment.environmentBrdfLutTexture } : {}),
+        ...(environment.environmentProbe ? { environmentProbe: environment.environmentProbe } : {})
+    };
+}
+const DISABLED_RENDERER_ENVIRONMENT_LIGHTING = {
+    color: [0, 0, 0],
+    intensity: 0,
+    proceduralMap: {
+        skyColor: [0, 0, 0],
+        horizonColor: [0, 0, 0],
+        groundColor: [0, 0, 0],
+        specularColor: [0, 0, 0],
+        intensity: 0,
+        specularIntensity: 0
+    },
+    environmentMapIntensity: 0,
+    environmentMapSpecularIntensity: 0
+};
+/**
+ * E3 step 4 verdict: this renderer default (ambient 0.42 + procedural
+ * 0.5/0.82) is already deleted on the conjunction path — and on every
+ * LIGHTING path — because `collectEnvironmentLighting` intercepts
+ * no-environment and legacy-fallback sources with the neutral room above
+ * before the default clone at its tail can run, and the conjunction
+ * requires LIGHTING. The constant itself is public API and stays
+ * byte-identical for flag-off callers; passed explicitly as authored
+ * lighting under the conjunction, its procedural terms are zeroed at the
+ * ForwardPass bind layer (frozen suppression) and its ambient remains the
+ * sole diffuse term (no sampled map).
+ */
+export const DEFAULT_RENDERER_ENVIRONMENT_LIGHTING = {
+    color: [0.78, 0.8, 0.84],
+    intensity: 0.42,
+    proceduralMap: {
+        skyColor: [0.64, 0.76, 0.94],
+        horizonColor: [0.94, 0.82, 0.62],
+        groundColor: [0.12, 0.13, 0.15],
+        specularColor: [1, 0.94, 0.78],
+        intensity: 0.5,
+        specularIntensity: 0.82
+    }
+};
+//# sourceMappingURL=Background.js.map

package/dist/renderer/Background.js.map

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

package/dist/renderer/CullingBatching.d.ts

@@ -0,0 +1,55 @@
+import type { RenderItem } from "../ForwardPass.js";
+import type { RenderCollectionDiagnostics } from "../Renderer.js";
+import type { RenderSource } from "../contracts/renderSource.js";
+import { type BatchPlan, type PlanBatchesOptions, type InstancedBatch } from "../batching/StaticMergePlanner.js";
+import { Frustum } from "@aura3d/math";
+import { Camera, type Mat4 } from "@aura3d/scene";
+export declare function explicitCullingFrustum(source: RenderSource, cameraViewProjection: Mat4 | undefined, camera: Camera | undefined): Frustum | undefined;
+export declare function cullExplicitRenderItems(items: readonly RenderItem[], frustum: Frustum | undefined, diagnostics: RenderCollectionDiagnostics, 
+/** 02-S5: receives culled items with `castShadow !== false`. */
+culledShadowCasters?: RenderItem[]): readonly RenderItem[];
+/**
+ * 02-S5: of the frustum-culled casters, keep those whose sun shadow can land
+ * in view. Each caster box is swept along the light's travel until its top
+ * reaches the lowest receiver (the ground footprint of its shadow); a sweep
+ * that intersects the view frustum keeps the caster. Casters whose shadow
+ * stays off-screen are dropped, so a large city does not inflate the cascade
+ * fit with buildings behind the camera.
+ */
+export declare function culledCastersReachingView(culled: readonly RenderItem[], receivers: readonly RenderItem[], frustum: Frustum | undefined, travel: readonly [number, number, number] | undefined): readonly RenderItem[];
+export declare function applyRendererOwnedStaticMeshConsolidation(source: RenderSource, items: readonly RenderItem[]): readonly RenderItem[];
+export declare function applyRendererOwnedStaticBatching(source: RenderSource, items: readonly RenderItem[]): readonly RenderItem[];
+/** C-31 `renderer.batching` report the engine diagnostics section publishes. */
+export interface Prd11BatchPlanReport {
+    readonly inputItems: number;
+    readonly outputDraws: number;
+    readonly instancedBatches: number;
+    readonly multiDrawBatches: number;
+    readonly reasonsNotBatched: Readonly<Record<string, number>>;
+    readonly planBuildMs: number;
+    readonly planVersion: number;
+}
+/** Latest plan report across all plan caches; `null`-safe for the diagnostics collector. */
+export declare function prd11LatestBatchPlanReport(): Prd11BatchPlanReport;
+/** Rewrites per-member matrices/colours in place for an unchanged set. */
+export declare function refreshInstancedBatch(batch: InstancedBatch): void;
+/** InstancedBatch → the RenderItems the legacy forward path submits. */
+export declare function synthesizeInstancedItems(batches: readonly InstancedBatch[]): RenderItem[];
+/**
+ * Per-source plan cache. `apply()` returns the transformed item list ready
+ * for draw submission; `lastReport` feeds `renderer.batching`.
+ */
+export declare class BatchPlanCache {
+    private signature;
+    private synthesized;
+    private plan;
+    private version;
+    lastReport: Prd11BatchPlanReport;
+    apply(items: readonly RenderItem[], options?: PlanBatchesOptions): RenderItem[];
+    /** Plan rebuilt this call — used by lane tests. */
+    get planVersion(): number;
+    get lastPlan(): BatchPlan | null;
+}
+/** Plan-cache accessor for the `prd11.batching` frame contributor (non-source item lists). */
+export declare function batchPlanCacheFor(key: object): BatchPlanCache;
+//# sourceMappingURL=CullingBatching.d.ts.map

package/dist/renderer/CullingBatching.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CullingBatching.d.ts","sourceRoot":"","sources":["../../../../../packages/rendering/src/renderer/CullingBatching.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAkB,MAAM,gBAAgB,CAAC;AAGjE,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,aAAa,CAAC;AAE/D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAG9D,OAAO,EAAe,KAAK,SAAS,EAAE,KAAK,kBAAkB,EAAE,KAAK,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAG3H,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC,OAAO,EAA2B,MAAM,EAAE,KAAK,IAAI,EAA0C,MAAM,eAAe,CAAC;AAEnH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,YAAY,EACpB,oBAAoB,EAAE,IAAI,GAAG,SAAS,EACtC,MAAM,EAAE,MAAM,GAAG,SAAS,GACzB,OAAO,GAAG,SAAS,CAOrB;AAED,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,SAAS,UAAU,EAAE,EAC5B,OAAO,EAAE,OAAO,GAAG,SAAS,EAC5B,WAAW,EAAE,2BAA2B;AACxC,gEAAgE;AAChE,mBAAmB,CAAC,EAAE,UAAU,EAAE,GACjC,SAAS,UAAU,EAAE,CAiCvB;AAQD;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,SAAS,UAAU,EAAE,EAC7B,SAAS,EAAE,SAAS,UAAU,EAAE,EAChC,OAAO,EAAE,OAAO,GAAG,SAAS,EAC5B,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,GACpD,SAAS,UAAU,EAAE,CAuBvB;AA+BD,wBAAgB,yCAAyC,CAAC,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,SAAS,UAAU,EAAE,GAAG,SAAS,UAAU,EAAE,CAgCnI;AAED,wBAAgB,gCAAgC,CAAC,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,SAAS,UAAU,EAAE,GAAG,SAAS,UAAU,EAAE,CAuC1H;AAgDD,gFAAgF;AAChF,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,iBAAiB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC7D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AASD,4FAA4F;AAC5F,wBAAgB,0BAA0B,IAAI,oBAAoB,CAEjE;AAmBD,0EAA0E;AAC1E,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI,CAYjE;AAED,wEAAwE;AACxE,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,SAAS,cAAc,EAAE,GAAG,UAAU,EAAE,CAezF;AAED;;;GAGG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,SAAS,CAAM;IACvB,OAAO,CAAC,WAAW,CAAoB;IACvC,OAAO,CAAC,IAAI,CAA0B;IACtC,OAAO,CAAC,OAAO,CAAK;IACpB,UAAU,EAAE,oBAAoB,CAAsB;IAEtD,KAAK,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,EAAE,OAAO,GAAE,kBAAuB,GAAG,UAAU,EAAE;IA2BnF,mDAAmD;IACnD,IAAI,WAAW,IAAI,MAAM,CAExB;IAED,IAAI,QAAQ,IAAI,SAAS,GAAG,IAAI,CAE/B;CACF;AAID,8FAA8F;AAC9F,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,CAO7D"}