@carbonenginejs/runtime 0.1.0-alpha.4 → 0.1.0-alpha.5

package/dist/trinity/eve/scene/EveSpaceScene.js

@@ -9,6 +9,7 @@ import { EveEntity as _EveEntity } from '../EveEntity.js';
 import { EveComponentRegistry as _EveComponentRegistry } from './components/EveComponentRegistry.js';
 import { Tr2PostProcess2 as _Tr2PostProcess } from '../../postProcess/Tr2PostProcess2.js';
 import { Tr2PostProcessAttributes as _Tr2PostProcessAttrib } from '../../postProcess/Tr2PostProcessAttributes.js';
+import { Tr2DataTextureManager as _Tr2DataTextureManage } from '../../shader/Tr2DataTextureManager.js';
 import { EveComponentType } from '../EveComponentTypes.js';
 import { EveUpdateContext as _EveUpdateContext } from '../EveUpdateContext.js';
 import { EveEffectRoot2 as _EveEffectRoot } from '../spaceObject/EveEffectRoot2.js';
@@ -154,13 +155,13 @@ new class extends _identity {
     /** m_shLightingManager (Tr2ShLightingManagerPtr) [PERSISTONLY] */
     shLightingManager = (_init_extra_ambientColor(this), _init_shLightingManager(this, null));
 
-    /** m_combinedPostProcessAttributes (Tr2PostProcessAttributesPtr) [READ] -
-     * default-constructed like Carbon's ctor CreateInstance (cpp:297); refreshed
+    /** m_combinedPostProcessAttributes (Tr2PostProcessAttributesPtr) [READ] -
+     * default-constructed like Carbon's ctor CreateInstance (cpp:297); refreshed
      * by UpdatePostProcessAttributes' re-export at MEDIUM_PRIORITY (cpp:407). */
     combinedPostProcessAttributes = (_init_extra_shLightingManager(this), _init_combinedPostProcessAttributes(this, new _Tr2PostProcessAttrib()));
 
     /** m_dataTextureMgr (Tr2DataTextureManagerPtr) [READ] */
-    dataTextureMgr = (_init_extra_combinedPostProcessAttributes(this), _init_dataTextureMgr(this, null));
+    dataTextureMgr = (_init_extra_combinedPostProcessAttributes(this), _init_dataTextureMgr(this, new _Tr2DataTextureManage()));
 
     /** m_dynamicObjectReflectionEnabled (bool) [READWRITE] */
     dynamicObjectReflectionEnabled = (_init_extra_dataTextureMgr(this), _init_dynamicObjectReflectionEnabled(this, true));
@@ -168,9 +169,9 @@ new class extends _identity {
     /** m_componentRegistry (EveComponentRegistryPtr) [READ] */
     componentRegistry = (_init_extra_dynamicObjectReflectionEnabled(this), _init_componentRegistry(this, new _EveComponentRegistry()));
 
-    /** m_cameraAttachmentParent (EveEffectRoot2Ptr) - protected Carbon scene
-     * entity, default-constructed like Carbon's ctor CreateInstance (cpp:287, no
-     * further setup applied). Consumers still optional-chain - deserialization
+    /** m_cameraAttachmentParent (EveEffectRoot2Ptr) - protected Carbon scene
+     * entity, default-constructed like Carbon's ctor CreateInstance (cpp:287, no
+     * further setup applied). Consumers still optional-chain - deserialization
      * may null it. */
     cameraAttachmentParent = (_init_extra_componentRegistry(this), _init_cameraAttachmentParent(this, new _EveEffectRoot()));
 
@@ -369,28 +370,28 @@ new class extends _identity {
     // scene instead of a module global.
     enablePostProcessDebugging = false;
 
-    /**
-     * Stamps the per-frame frustum/threshold/LOD state onto the scene-owned
-     * update context (Carbon EveSpaceScene::Update cpp:475-484, identical to the
-     * already-updated fast path cpp:448-457). Carbon derives the frustum from
-     * the Tr2Renderer view statics and reads the thresholds from console vars
-     * divided by m_upscalingAmount (=1 by default, cpp:221); in CarbonEngineJS
-     * the driver derives the frustum from the same renderContext state it
-     * stamped and supplies the thresholds explicitly (pre-divided if it ever
-     * upscales). Defaults are the Carbon console-var defaults (cpp:75-84).
-     * The raytracing flag is Carbon's `m_shadowQuality == SHADOW_RAYTRACED &&
-     * m_enableShadows` (cpp:457/484) - the driver computes it; the scene does
-     * not. Stamps unconditionally: Carbon's same-frame fast path restamps
-     * regardless of m_update (cpp:444-462); only the cold path skips stamping
-     * when !m_update (cpp:466 precedes 475) - benign divergence.
-     * @param {Object} [options]
-     * @param {Object|null} [options.frustum] - a ready TriFrustum, held by reference
-     * @param {Number} [options.visibilityThreshold]
-     * @param {Number} [options.lowDetailThreshold]
-     * @param {Number} [options.mediumDetailThreshold]
-     * @param {Number} [options.highDetailThreshold]
-     * @param {Number} [options.lodFactor]
-     * @param {Boolean} [options.raytracingEnabled]
+    /**
+     * Stamps the per-frame frustum/threshold/LOD state onto the scene-owned
+     * update context (Carbon EveSpaceScene::Update cpp:475-484, identical to the
+     * already-updated fast path cpp:448-457). Carbon derives the frustum from
+     * the Tr2Renderer view statics and reads the thresholds from console vars
+     * divided by m_upscalingAmount (=1 by default, cpp:221); in CarbonEngineJS
+     * the driver derives the frustum from the same renderContext state it
+     * stamped and supplies the thresholds explicitly (pre-divided if it ever
+     * upscales). Defaults are the Carbon console-var defaults (cpp:75-84).
+     * The raytracing flag is Carbon's `m_shadowQuality == SHADOW_RAYTRACED &&
+     * m_enableShadows` (cpp:457/484) - the driver computes it; the scene does
+     * not. Stamps unconditionally: Carbon's same-frame fast path restamps
+     * regardless of m_update (cpp:444-462); only the cold path skips stamping
+     * when !m_update (cpp:466 precedes 475) - benign divergence.
+     * @param {Object} [options]
+     * @param {Object|null} [options.frustum] - a ready TriFrustum, held by reference
+     * @param {Number} [options.visibilityThreshold]
+     * @param {Number} [options.lowDetailThreshold]
+     * @param {Number} [options.mediumDetailThreshold]
+     * @param {Number} [options.highDetailThreshold]
+     * @param {Number} [options.lodFactor]
+     * @param {Boolean} [options.raytracingEnabled]
      */
     StampFrameContext({
       frustum = null,
@@ -411,23 +412,23 @@ new class extends _identity {
       context.raytracingEnabled = !!raytracingEnabled;
     }
 
-    /**
-     * Per-frame scene update, ported from Carbon EveSpaceScene::Update: stamps the
-     * scene-owned frame context (time, origin, data-texture manager), then drives
-     * every collection in Carbon's order - background objects, warp tunnel,
-     * starfield, static particles, data textures, distance fields, lensflares,
-     * virtual camera system, curve sets, then all space/UI objects synchronous
-     * first and asynchronous second (Carbon parallelizes the async pass on a task
-     * group; JS runs it sequentially). Then combines the post-process attributes
-     * (cpp:584) and finally reads the sun direction from the sun ball
-     * (cpp:589-596).
-     *
-     * Adapted - deferred vs Carbon: the recording-frame dedup fast path,
-     * frustum/threshold/LOD/raytracing stamping (now the driver's job via
-     * StampFrameContext, called BEFORE Update), planet update (planet
-     * view-matrix swap unported), and main-thread action flush (N/A).
-     * @param {Number} realTime
-     * @param {Number} simTime
+    /**
+     * Per-frame scene update, ported from Carbon EveSpaceScene::Update: stamps the
+     * scene-owned frame context (time, origin, data-texture manager), then drives
+     * every collection in Carbon's order - background objects, warp tunnel,
+     * starfield, static particles, data textures, distance fields, lensflares,
+     * virtual camera system, curve sets, then all space/UI objects synchronous
+     * first and asynchronous second (Carbon parallelizes the async pass on a task
+     * group; JS runs it sequentially). Then combines the post-process attributes
+     * (cpp:584) and finally reads the sun direction from the sun ball
+     * (cpp:589-596).
+     *
+     * Adapted - deferred vs Carbon: the recording-frame dedup fast path,
+     * frustum/threshold/LOD/raytracing stamping (now the driver's job via
+     * StampFrameContext, called BEFORE Update), planet update (planet
+     * view-matrix swap unported), and main-thread action flush (N/A).
+     * @param {Number} realTime
+     * @param {Number} simTime
      */
     Update(realTime, simTime) {
       if (!this.update) {
@@ -436,7 +437,7 @@ new class extends _identity {
       const context = this.updateContext;
       context.SetTime(simTime);
       context.UpdateOrigin(this.ballpark);
-      context.dataTextureManager = this.dataTextureMgr;
+      context.SetDataTextureManager(this.dataTextureMgr);
       for (const object of this.backgroundObjects) {
         object?.UpdateSyncronous(context);
       }
@@ -504,20 +505,20 @@ new class extends _identity {
       throw new Error("EveSpaceScene.PickObjectAndAreaID is not implemented in CarbonEngineJS.");
     }
 
-    /**
-     * Carbon EveSpaceScene::PickInfinity (cpp:4039-4050): the world-space
-     * DIRECTION a screen pixel points along - the pick ray with nothing to hit,
-     * which is what a click on empty space resolves to. Pure math, no readback.
-     *
-     * @param {Number} x - screen x, in pixels
-     * @param {Number} y - screen y, in pixels
-     * @param {Float32Array} projection - the projection matrix
-     * @param {Float32Array} view - the view matrix
-     * @param {Object} [viewport] - { x, y, width, height }; the frame's render
-     *   context supplies one when this is omitted
-     * @param {Float32Array} [out] - caller-owned direction
-     * @returns {Float32Array|null} the normalized world direction, or null when
-     *   either matrix cannot be inverted
+    /**
+     * Carbon EveSpaceScene::PickInfinity (cpp:4039-4050): the world-space
+     * DIRECTION a screen pixel points along - the pick ray with nothing to hit,
+     * which is what a click on empty space resolves to. Pure math, no readback.
+     *
+     * @param {Number} x - screen x, in pixels
+     * @param {Number} y - screen y, in pixels
+     * @param {Float32Array} projection - the projection matrix
+     * @param {Float32Array} view - the view matrix
+     * @param {Object} [viewport] - { x, y, width, height }; the frame's render
+     *   context supplies one when this is omitted
+     * @param {Float32Array} [out] - caller-owned direction
+     * @returns {Float32Array|null} the normalized world direction, or null when
+     *   either matrix cannot be inverted
      */
     PickInfinity(x, y, projection, view, viewport = null, out = vec3.create()) {
       const resolved = viewport ?? this.updateContext?.renderContext?.GetViewport?.();
@@ -526,23 +527,23 @@ new class extends _identity {
       return ray ? vec3.copy(out, ray.direction) : null;
     }
 
-    /**
-     * The per-frame CPU visibility pass, ported from the [VISIBILITY] block of
-     * Carbon EveSpaceScene::GatherBatches (EveSpaceScene.cpp:1443-1467; the
-     * enclosing display gate is BeginRender cpp:1299-1302). Carbon's
-     * Tr2ParallelDo loops (objects cpp:1445-1447, staticParticles cpp:1454-1456,
-     * planets cpp:1458-1460) run sequentially in the same order; the lensflare
-     * loop is sequential in Carbon too (cpp:1462-1466). LOD stamping (lodLevel,
-     * isVisible, pixel diameters) happens INSIDE each object's UpdateVisibility;
-     * per-object display gates live there too - the scene does not pre-filter.
-     * uiObjects are never visited (Carbon never culls them). The camera parent's
-     * SetTransform is pure decomposition (EveEffectRoot2.cpp:677-680 Decompose)
-     * - no composition, so no row-vector operand swap here; this per-gather
-     * Sync/Async pair is the camera parent's ONLY update, so its world transform
-     * is the camera pose of the frame being gathered (cpp:1449-1452).
-     * @param {Float32Array} inverseView - the inverse view matrix
-     *   (updateContext.renderContext.GetInverseViewTransform(); Carbon reads the
-     *   Tr2Renderer static at cpp:1449)
+    /**
+     * The per-frame CPU visibility pass, ported from the [VISIBILITY] block of
+     * Carbon EveSpaceScene::GatherBatches (EveSpaceScene.cpp:1443-1467; the
+     * enclosing display gate is BeginRender cpp:1299-1302). Carbon's
+     * Tr2ParallelDo loops (objects cpp:1445-1447, staticParticles cpp:1454-1456,
+     * planets cpp:1458-1460) run sequentially in the same order; the lensflare
+     * loop is sequential in Carbon too (cpp:1462-1466). LOD stamping (lodLevel,
+     * isVisible, pixel diameters) happens INSIDE each object's UpdateVisibility;
+     * per-object display gates live there too - the scene does not pre-filter.
+     * uiObjects are never visited (Carbon never culls them). The camera parent's
+     * SetTransform is pure decomposition (EveEffectRoot2.cpp:677-680 Decompose)
+     * - no composition, so no row-vector operand swap here; this per-gather
+     * Sync/Async pair is the camera parent's ONLY update, so its world transform
+     * is the camera pose of the frame being gathered (cpp:1449-1452).
+     * @param {Float32Array} inverseView - the inverse view matrix
+     *   (updateContext.renderContext.GetInverseViewTransform(); Carbon reads the
+     *   Tr2Renderer static at cpp:1449)
      */
     UpdateVisibility(inverseView) {
       if (!this.display) {
@@ -569,17 +570,17 @@ new class extends _identity {
       }
     }
 
-    /** Gathers batchable renderables from the scene's objects for the batch
-     * collection pass - the [GATHER] block of Carbon
-     * EveSpaceScene::GatherBatches (EveSpaceScene.cpp:1470-1507): m_objects in
-     * list order (cpp:1470-1475), then cameraAttachmentParent pushed LAST
-     * (cpp:1476), then the staticParticles leg (cpp:1504-1507; Carbon signature
-     * `GetRenderables(frustum, renderables)`, EveSceneStaticParticles.h - kept
-     * with the out-parameter last per convention). Objects self-filter on the
-     * visibility flags stamped by UpdateVisibility, so the array handed to
-     * CjsBatchManager.Collect is pre-culled and this aggregation stays GPU-free.
-     * The impostor-manager argument (cpp:1478-1502) is dropped - engine-owned.
-     * Gather order matters downstream: the opaque accumulator receives batches
+    /** Gathers batchable renderables from the scene's objects for the batch
+     * collection pass - the [GATHER] block of Carbon
+     * EveSpaceScene::GatherBatches (EveSpaceScene.cpp:1470-1507): m_objects in
+     * list order (cpp:1470-1475), then cameraAttachmentParent pushed LAST
+     * (cpp:1476), then the staticParticles leg (cpp:1504-1507; Carbon signature
+     * `GetRenderables(frustum, renderables)`, EveSceneStaticParticles.h - kept
+     * with the out-parameter last per convention). Objects self-filter on the
+     * visibility flags stamped by UpdateVisibility, so the array handed to
+     * CjsBatchManager.Collect is pre-culled and this aggregation stays GPU-free.
+     * The impostor-manager argument (cpp:1478-1502) is dropped - engine-owned.
+     * Gather order matters downstream: the opaque accumulator receives batches
      * in gather order before Finalize sorts. */
     GetRenderables(out = []) {
       if (!this.display) {
@@ -593,18 +594,18 @@ new class extends _identity {
       return out;
     }
 
-    /**
-     * Refreshes the scene default's attribute snapshot, gathers every registered
-     * PostProcessOwner's attributes, priority-blends them into the combined
-     * post-process, copies the six engine effects through from the scene
-     * default, and re-exports the result (Carbon
-     * EveSpaceScene::UpdatePostProcessAttributes, EveSpaceScene.cpp:346-413).
-     * Sort is descending by priority (cpp:372-377); Carbon's std::sort is
-     * unstable while JS sort is stable - equal-priority ties keep registry
-     * insertion order, which is blend-order-independent for every Sum-accumulated
-     * attribute (the whole tie group is normalized together); only MaxWeight
-     * ties at exactly equal weight (string paths / bools / DoF shape) could
-     * differ from C++.
+    /**
+     * Refreshes the scene default's attribute snapshot, gathers every registered
+     * PostProcessOwner's attributes, priority-blends them into the combined
+     * post-process, copies the six engine effects through from the scene
+     * default, and re-exports the result (Carbon
+     * EveSpaceScene::UpdatePostProcessAttributes, EveSpaceScene.cpp:346-413).
+     * Sort is descending by priority (cpp:372-377); Carbon's std::sort is
+     * unstable while JS sort is stable - equal-priority ties keep registry
+     * insertion order, which is blend-order-independent for every Sum-accumulated
+     * attribute (the whole tie group is normalized together); only MaxWeight
+     * ties at exactly equal weight (string paths / bools / DoF shape) could
+     * differ from C++.
      */
     UpdatePostProcessAttributes() {
       if (!this.display) {
@@ -666,7 +667,7 @@ new class extends _identity {
       }
     }
 
-    /** Carbon method GetPostProcess (EveSpaceScene.cpp:420-427): the combined
+    /** Carbon method GetPostProcess (EveSpaceScene.cpp:420-427): the combined
      * post-process, or null while the scene is not displayed. */
     GetPostProcess() {
       if (!this.display) {
@@ -675,17 +676,17 @@ new class extends _identity {
       return this.#combinedPostProcess;
     }
 
-    /**
-     * Blends every registered EveLightingOverride against the scene baseline and
-     * stamps currentSunColor / currentNebulaIntensity /
-     * currentReflectionIntensity - the lighting-override block of Carbon
-     * EveSpaceScene::BeginRender (EveSpaceScene.cpp:1333-1363). The baseline is
-     * appended AFTER the sort at raw priority -1 - one below
-     * SCENE_DEFAULT_PRIORITY=0, outside the legal enum range (Carbon casts -1,
-     * cpp:1343) - so it always sits last. Scalar/color math only - no matrix
-     * compositions, no row-vector swaps anywhere in this method. Same
-     * stable-sort note as UpdatePostProcessAttributes - here fully benign, the
-     * blend is symmetric within a tie group.
+    /**
+     * Blends every registered EveLightingOverride against the scene baseline and
+     * stamps currentSunColor / currentNebulaIntensity /
+     * currentReflectionIntensity - the lighting-override block of Carbon
+     * EveSpaceScene::BeginRender (EveSpaceScene.cpp:1333-1363). The baseline is
+     * appended AFTER the sort at raw priority -1 - one below
+     * SCENE_DEFAULT_PRIORITY=0, outside the legal enum range (Carbon casts -1,
+     * cpp:1343) - so it always sits last. Scalar/color math only - no matrix
+     * compositions, no row-vector swaps anywhere in this method. Same
+     * stable-sort note as UpdatePostProcessAttributes - here fully benign, the
+     * blend is symmetric within a tie group.
      */
     BlendLightingOverrides() {
       if (!this.display) {
@@ -723,30 +724,30 @@ new class extends _identity {
       this.currentReflectionIntensity = over.reflectionIntensity;
     }
 
-    /**
-     * Runs Carbon's portable froxel-fog blend against the scene-owned registry
-     * and update context. The frame driver calls this immediately after lighting
-     * overrides and before visibility/gather.
+    /**
+     * Runs Carbon's portable froxel-fog blend against the scene-owned registry
+     * and update context. The frame driver calls this immediately after lighting
+     * overrides and before visibility/gather.
      */
     UpdateFogSettings() {
       this.volumetricsRenderer.UpdateFogSettings(this.componentRegistry, this.updateContext);
     }
 
-    /**
-     * Drives the injected light manager through Carbon's dynamic-light gather
-     * (EveSpaceScene::BeginRender, EveSpaceScene.cpp:1396-1416, AFTER
-     * GatherBatches cpp:1387): shadow quality, clear (runs even with zero owners
-     * - stale lights must drop), frustum, LOD cutoff, then every registered
-     * LightOwner's GetLights (Carbon Tr2ParallelFor chunk-20 cpp:1405-1413; JS
-     * sequential in collection order), then ResolveLightData. No JS
-     * Tr2LightManager class exists - the manager is a duck and every manager
-     * call is optional-chained so a partial duck still gets the owner loop.
-     * Carbon runs the block only when a manager instance exists (dynamic
-     * lighting on) - a null manager is a no-op. The recording frame number
-     * Carbon passes to SetShadowQuality and the renderContext it passes to Clear
-     * are engine recording state - the JS Clear receives the frame's
-     * renderContext for ducks that want it.
-     * @param {Object|null} lightManager
+    /**
+     * Drives the injected light manager through Carbon's dynamic-light gather
+     * (EveSpaceScene::BeginRender, EveSpaceScene.cpp:1396-1416, AFTER
+     * GatherBatches cpp:1387): shadow quality, clear (runs even with zero owners
+     * - stale lights must drop), frustum, LOD cutoff, then every registered
+     * LightOwner's GetLights (Carbon Tr2ParallelFor chunk-20 cpp:1405-1413; JS
+     * sequential in collection order), then ResolveLightData. No JS
+     * Tr2LightManager class exists - the manager is a duck and every manager
+     * call is optional-chained so a partial duck still gets the owner loop.
+     * Carbon runs the block only when a manager instance exists (dynamic
+     * lighting on) - a null manager is a no-op. The recording frame number
+     * Carbon passes to SetShadowQuality and the renderContext it passes to Clear
+     * are engine recording state - the JS Clear receives the frame's
+     * renderContext for ducks that want it.
+     * @param {Object|null} lightManager
      */
     GatherLights(lightManager) {
       if (!lightManager || !this.display) {
@@ -762,18 +763,18 @@ new class extends _identity {
       lightManager.ResolveLightData();
     }
 
-    /**
-     * Carbon EveSpaceScene::UpdateShLighting (cpp:1685-1703): hands every
-     * secondary-lighting receiver the scene's SH manager, so each one samples the
-     * bounce light at its own position. A scene with no manager does nothing, as
-     * Carbon does.
-     *
-     * Carbon runs this at the very END of the gather (cpp:1524, after
-     * FinalizeBatches), and over a parallel range; the JS pass is sequential
-     * because the receivers write only their own records and share no state.
-     *
-     * @param {Array} objects - the frame's visible objects
-     * @returns {Number} how many receivers were updated
+    /**
+     * Carbon EveSpaceScene::UpdateShLighting (cpp:1685-1703): hands every
+     * secondary-lighting receiver the scene's SH manager, so each one samples the
+     * bounce light at its own position. A scene with no manager does nothing, as
+     * Carbon does.
+     *
+     * Carbon runs this at the very END of the gather (cpp:1524, after
+     * FinalizeBatches), and over a parallel range; the JS pass is sequential
+     * because the receivers write only their own records and share no state.
+     *
+     * @param {Array} objects - the frame's visible objects
+     * @returns {Number} how many receivers were updated
      */
     UpdateShLighting(objects = []) {
       if (!this.shLightingManager) {
@@ -790,11 +791,11 @@ new class extends _identity {
       return updated;
     }
 
-    /**
-     * The scene's own per-frame vertex record (Carbon m_perFrameVS,
-     * EveSpaceScene.h:300). Persistent, not arena-leased: it is rewritten each
-     * frame and bound once, and the PS fill reads m_upscalingAmount back out of
-     * the same pass.
+    /**
+     * The scene's own per-frame vertex record (Carbon m_perFrameVS,
+     * EveSpaceScene.h:300). Persistent, not arena-leased: it is rewritten each
+     * frame and bound once, and the PS fill reads m_upscalingAmount back out of
+     * the same pass.
      */
     #perFrameVS = RawData.create("EveSpaceScenePerFrameVSData");
 
@@ -811,33 +812,33 @@ new class extends _identity {
       return this.#perFramePS;
     }
 
-    /**
-     * Fills the per-frame VERTEX constants (Carbon
-     * EveSpaceScene::PopulatePerFrameVSData, cpp:3015-3068).
-     *
-     * Adapted in one respect, the same way StampFrameContext is: Carbon reads
-     * the camera off `Tr2Renderer` statics and the render-target/viewport sizes
-     * off `renderContext.m_esm`, neither of which exists GPU-free here. The
-     * driver passes them in `frame` instead. Everything the scene itself owns -
-     * sun, fog, env-map rotation, the previous frame's view/projection - is read
-     * from the scene, as Carbon does.
-     *
-     * Matrices are stored TRANSPOSED because the shaders are column_major, with
-     * one deliberate exception Carbon calls out at cpp:3023: the value wanted for
-     * `ViewInverseTransposeMat` is already a transpose, so transposing it again
-     * cancels and the inverse view goes in as-is.
-     *
-     * @param {Object} renderContext - the frame's Tr2RenderContext
-     * @param {Object} [frame] - the engine-supplied state Carbon reads statically
-     * @param {Number} [frame.renderTargetWidth]
-     * @param {Number} [frame.renderTargetHeight]
-     * @param {Number} [frame.aspectRatio]
-     * @param {Number} [frame.animationTime] - Tr2Renderer::GetAnimationTime
-     * @param {Object|null} [frame.deviceViewport] - {width, height}
-     * @param {Object|null} [frame.projectionTransform] - the NON reversed-depth
-     *   projection, which Carbon uses only to recover the field of view
-     * @param {Object} [out] - the record to fill; defaults to the scene's own
-     * @returns {Object} the filled record
+    /**
+     * Fills the per-frame VERTEX constants (Carbon
+     * EveSpaceScene::PopulatePerFrameVSData, cpp:3015-3068).
+     *
+     * Adapted in one respect, the same way StampFrameContext is: Carbon reads
+     * the camera off `Tr2Renderer` statics and the render-target/viewport sizes
+     * off `renderContext.m_esm`, neither of which exists GPU-free here. The
+     * driver passes them in `frame` instead. Everything the scene itself owns -
+     * sun, fog, env-map rotation, the previous frame's view/projection - is read
+     * from the scene, as Carbon does.
+     *
+     * Matrices are stored TRANSPOSED because the shaders are column_major, with
+     * one deliberate exception Carbon calls out at cpp:3023: the value wanted for
+     * `ViewInverseTransposeMat` is already a transpose, so transposing it again
+     * cancels and the inverse view goes in as-is.
+     *
+     * @param {Object} renderContext - the frame's Tr2RenderContext
+     * @param {Object} [frame] - the engine-supplied state Carbon reads statically
+     * @param {Number} [frame.renderTargetWidth]
+     * @param {Number} [frame.renderTargetHeight]
+     * @param {Number} [frame.aspectRatio]
+     * @param {Number} [frame.animationTime] - Tr2Renderer::GetAnimationTime
+     * @param {Object|null} [frame.deviceViewport] - {width, height}
+     * @param {Object|null} [frame.projectionTransform] - the NON reversed-depth
+     *   projection, which Carbon uses only to recover the field of view
+     * @param {Object} [out] - the record to fill; defaults to the scene's own
+     * @returns {Object} the filled record
      */
     PopulatePerFrameVSData(renderContext, frame = {}, out = this.#perFrameVS) {
       const view = renderContext.GetViewTransform();
@@ -889,30 +890,30 @@ new class extends _identity {
       return out;
     }
 
-    /**
-     * Fills the per-frame PIXEL constants (Carbon
-     * EveSpaceScene::PopulatePerFramePSData, cpp:3075-3202). Same `frame`
-     * adaptation as the vertex fill.
-     *
-     * The cascaded-shadow block (ShadowMapValues / CascadeRanges /
-     * ShadowMatrixVal / SplitInfo) is filled only when a shadow map is passed,
-     * exactly as Carbon's `if( shadowMap )` gate does; without one the record
-     * leaves the persistent cascade bytes untouched. `ShadowCameraRange` remains
-     * disabled, so stale cascade bytes are not consumed until a map is supplied
-     * again.
-     *
-     * @param {Object} renderContext - the frame's Tr2RenderContext
-     * @param {Object} [frame] - as PopulatePerFrameVSData, plus:
-     * @param {Number} [frame.frameIndex] - Tr2Renderer::GetCurrentFrameCounter
-     * @param {Number} [frame.gammaBrightness]
-     * @param {Number} [frame.sceneMipLodBias] - the upscaler's bias, plus the
-     *   scene post-process's own; the upscaling info is engine state
-     * @param {Number} [frame.inverseShadowMapAtlasSize] - 0 with no light manager
-     * @param {Number} [frame.shadowMapAtlasEntryMinSizeLog2]
-     * @param {Tr2ShadowMap|null} [shadowMap=this.cascadedShadowMap] - the owned
-     *   cascaded shadow map; explicit null disables cascade packing
-     * @param {Object} [out] - the record to fill; defaults to the scene's own
-     * @returns {Object} the filled record
+    /**
+     * Fills the per-frame PIXEL constants (Carbon
+     * EveSpaceScene::PopulatePerFramePSData, cpp:3075-3202). Same `frame`
+     * adaptation as the vertex fill.
+     *
+     * The cascaded-shadow block (ShadowMapValues / CascadeRanges /
+     * ShadowMatrixVal / SplitInfo) is filled only when a shadow map is passed,
+     * exactly as Carbon's `if( shadowMap )` gate does; without one the record
+     * leaves the persistent cascade bytes untouched. `ShadowCameraRange` remains
+     * disabled, so stale cascade bytes are not consumed until a map is supplied
+     * again.
+     *
+     * @param {Object} renderContext - the frame's Tr2RenderContext
+     * @param {Object} [frame] - as PopulatePerFrameVSData, plus:
+     * @param {Number} [frame.frameIndex] - Tr2Renderer::GetCurrentFrameCounter
+     * @param {Number} [frame.gammaBrightness]
+     * @param {Number} [frame.sceneMipLodBias] - the upscaler's bias, plus the
+     *   scene post-process's own; the upscaling info is engine state
+     * @param {Number} [frame.inverseShadowMapAtlasSize] - 0 with no light manager
+     * @param {Number} [frame.shadowMapAtlasEntryMinSizeLog2]
+     * @param {Tr2ShadowMap|null} [shadowMap=this.cascadedShadowMap] - the owned
+     *   cascaded shadow map; explicit null disables cascade packing
+     * @param {Object} [out] - the record to fill; defaults to the scene's own
+     * @returns {Object} the filled record
      */
     PopulatePerFramePSData(renderContext, frame = {}, shadowMap = this.cascadedShadowMap, out = this.#perFramePS) {
       if (shadowMap !== null && !(shadowMap instanceof _Tr2ShadowMap)) {
@@ -979,10 +980,10 @@ new class extends _identity {
       return out;
     }
 
-    /**
-     * The SunData block both fills share (cpp:3035-3039 / 3085-3089). The
-     * direction is normalized AND negated: shaders work with the direction TO
-     * the light, not the direction it travels.
+    /**
+     * The SunData block both fills share (cpp:3035-3039 / 3085-3089). The
+     * direction is normalized AND negated: shaders work with the direction TO
+     * the light, not the direction it travels.
      */
     #FillSunData(out) {
       vec3.normalize(sunDirectionScratch, this.sunDirection);
@@ -990,10 +991,10 @@ new class extends _identity {
       out.Set("Sun.DiffuseColor", this.currentSunColor);
     }
 
-    /**
-     * FOV both ways - width in x, height in y (cpp:3046-3047 / 3103-3104).
-     * Carbon recovers it from the NON reversed-depth projection, so a driver
-     * that reverses depth must pass the original in `frame.projectionTransform`.
+    /**
+     * FOV both ways - width in x, height in y (cpp:3046-3047 / 3103-3104).
+     * Carbon recovers it from the NON reversed-depth projection, so a driver
+     * that reverses depth must pass the original in `frame.projectionTransform`.
      */
     #FillFovXY(out, frame) {
       const source = frame.projectionTransform;
@@ -1001,10 +1002,10 @@ new class extends _identity {
       out.Set("FovXY", [fovY * (frame.aspectRatio ?? 1), fovY]);
     }
 
-    /**
-     * The cascaded-shadow block (cpp:3163-3190). Each cascade's shadow matrix is
-     * rebased into the current view, flipped in y, remapped from (-1,+1) to
-     * (0,1), then scaled and offset into its cell of the 8x2 atlas.
+    /**
+     * The cascaded-shadow block (cpp:3163-3190). Each cascade's shadow matrix is
+     * rebased into the current view, flipped in y, remapped from (-1,+1) to
+     * (0,1), then scaled and offset into its cell of the 8x2 atlas.
      */
     #FillShadowCascades(out, shadowMap, renderContext) {
       const split = shadowMap.GetPerSplitData();
@@ -1037,8 +1038,8 @@ new class extends _identity {
       out.Set("SplitInfo", split.SplitInfo);
     }
 
-    /** Carbon method ReregisterEntities (MAP_METHOD_AND_WRAP, cpp:4064-4089).
-     * Guarded no-op after ClearComponentRegistry has nulled the registry
+    /** Carbon method ReregisterEntities (MAP_METHOD_AND_WRAP, cpp:4064-4089).
+     * Guarded no-op after ClearComponentRegistry has nulled the registry
      * (destroy-only path; Carbon would never call this afterwards). */
     ReregisterEntities() {
       if (!this.componentRegistry) {
@@ -1056,11 +1057,11 @@ new class extends _identity {
       }
     }
 
-    /** Carbon method ClearComponentRegistry (EveSpaceScene.cpp:4091-4099, called
-     * from the destructor cpp:322). Entity component-state is deliberately NOT
-     * cleared beyond what Clear() does - either the scene is being destroyed
-     * (entities go too) or entities move to another scene and re-register there.
-     * The JS registry Clear() additionally detaches entity.registry when it
+    /** Carbon method ClearComponentRegistry (EveSpaceScene.cpp:4091-4099, called
+     * from the destructor cpp:322). Entity component-state is deliberately NOT
+     * cleared beyond what Clear() does - either the scene is being destroyed
+     * (entities go too) or entities move to another scene and re-register there.
+     * The JS registry Clear() additionally detaches entity.registry when it
      * points at this registry - strictly more hygienic than Carbon; kept. */
     ClearComponentRegistry() {
       this.componentRegistry?.Clear();
@@ -1077,21 +1078,21 @@ new class extends _identity {
       return this.Update(time, time);
     }
 
-    /**
-     * Carbon SimplePriorityBlend (PriorityBlend.h:371-413) specialized to the
-     * IEveLightingOverride::Overrides value type
-     * { sunColor: vec4, sunIntensity, backgroundIntensity, reflectionIntensity }
-     * (EveChildLightingOverride.h:15-32) - `+` and `* weight` componentwise.
-     * Walks the (already priority-desc-sorted) list in equal-priority groups:
-     *   factor = (1 / max(groupTotal, 1)) * remainingWeight
-     * then subtracts the UNCLAMPED group total from remainingWeight. Two quirks
-     * preserved exactly: (a) a group with total intensity 0.3 contributes at
-     * weight 0.3*remaining and leaves 0.7 for lower priorities; (b) a group with
-     * total 2 is normalized to consume exactly remainingWeight and terminates
-     * (remaining goes to -1).
-     * @param {Array} sources - [{ priority, intensity, value }] sorted high->low
-     * @returns {{ sunColor: Float32Array, sunIntensity: Number,
-     *   backgroundIntensity: Number, reflectionIntensity: Number }}
+    /**
+     * Carbon SimplePriorityBlend (PriorityBlend.h:371-413) specialized to the
+     * IEveLightingOverride::Overrides value type
+     * { sunColor: vec4, sunIntensity, backgroundIntensity, reflectionIntensity }
+     * (EveChildLightingOverride.h:15-32) - `+` and `* weight` componentwise.
+     * Walks the (already priority-desc-sorted) list in equal-priority groups:
+     *   factor = (1 / max(groupTotal, 1)) * remainingWeight
+     * then subtracts the UNCLAMPED group total from remainingWeight. Two quirks
+     * preserved exactly: (a) a group with total intensity 0.3 contributes at
+     * weight 0.3*remaining and leaves 0.7 for lower priorities; (b) a group with
+     * total 2 is normalized to consume exactly remainingWeight and terminates
+     * (remaining goes to -1).
+     * @param {Array} sources - [{ priority, intensity, value }] sorted high->low
+     * @returns {{ sunColor: Float32Array, sunIntensity: Number,
+     *   backgroundIntensity: Number, reflectionIntensity: Number }}
      */
   }];
   EveVisualizeMethod = EveVisualizeMethod;